mvanhorn Gorgias — Printing Press CLI
Prerequisites: Install the CLI
This skill drives the gorgias-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/binon macOS/Linux and%LOCALAPPDATA%\Programs\PrintingPress\binon Windows:npx -y @mvanhorn/printing-press-library install gorgias --cli-only - Verify:
gorgias-pp-cli --version - Ensure the reported install directory is on
$PATHfor the agent/runtime that will invoke this skill.
If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):
go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/gorgias/cmd/gorgias-pp-cli@latest
If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.
When to Use This CLI
Reach for gorgias-pp-cli whenever a support workflow needs to read or write Gorgias data: pulling recent tickets for digest, searching past conversations for context, automating bulk tag/macro applications, monitoring oncall queues, or building agent-driven escalation flows. The sibling MCP server lets LLMs drive the same surface without shelling out.
Unique Capabilities
These capabilities aren't available in any other tool for this API.
gorgias-pp-cli doctor --json— Probes /account with the configured credentials and reportscredentials: validonly when an authenticated call succeeds.Saves the first-five-minutes credential-debug cycle when wiring up an agent.
gorgias-pp-cli doctor --jsongorgias-pp-cli sync --resources tickets --since 7d && gorgias-pp-cli search 'refund' --agent— Syncs API data to a local SQLite DB so subsequent searches, analytics, and joins run without hitting the API.Makes repeated agent-driven lookups (e.g. searching for similar past tickets) practical at scale. Ticket
--sinceuses documentedorder_by=updated_datetime:descplus local filtering; do not add undocumented filters likeupdated_datetime__gteunless Gorgias documents them and a live smoke confirms them.gorgias-pp-cli sync --resources tickets --since 30d --json
Command Reference
account — Account-level settings and tenant metadata
gorgias-pp-cli account get— Retrieve the current Gorgias account's metadata: subdomain, plan, billing state, and account-level flags. Use this...gorgias-pp-cli account settings-create— Create a new account-level settings record for the current Gorgias tenant. Use when bootstrapping a fresh tenant or...gorgias-pp-cli account settings-list— List the global settings on the current Gorgias account (business hours, language, default channels, notification...gorgias-pp-cli account settings-update— Update an account settings record byid. Use this to flip a tenant-wide flag, change business hours, or adjust a...
custom-fields — Define and manage custom fields on tickets and customers
gorgias-pp-cli custom-fields create— Define a new custom field on tickets or customers (the only supportedobject_typevalues). Required body:...gorgias-pp-cli custom-fields get— Fetch a single custom field definition byid, returning its data type, label, target object, and option list. Use...gorgias-pp-cli custom-fields list— List custom field definitions for a singleobject_type(TicketorCustomer— REQUIRED query param)....gorgias-pp-cli custom-fields update— Update one custom field definition byid— relabel it, change its options, or toggle visibility. Note: this...gorgias-pp-cli custom-fields update-all— Bulk-update multiple custom field definitions in one call (no path id). Useful when reordering picklist options or...
customers — Read and write Gorgias customer records (CRM core)
gorgias-pp-cli customers create— Create a new customer record. Passname,email, optionalchannels(email/phone/social handles), anddatafor...gorgias-pp-cli customers custom-fields-list— List every custom field value attached to a single customer (id). Use to read CRM-style attributes (lifetime...gorgias-pp-cli customers custom-fields-set— Set a single custom field value on a customer: first{id}is the customer, second{id}is the custom field. Use...gorgias-pp-cli customers custom-fields-set-all— Bulk-set custom field values on a single customer (id) — pass an array of field/value pairs. Preferred over the...gorgias-pp-cli customers custom-fields-unset— Clear a custom field value on a customer: first{id}is the customer ID, second{id}is the custom field ID. Use...gorgias-pp-cli customers data-update— Set a customer'sdatablob (idin path). Body:data(required) plus optionalversionfor last-write-wins...gorgias-pp-cli customers delete— Delete one customer byid. Hard-deletes the record and may cascade to associated tickets/messages depending on...gorgias-pp-cli customers delete-all— Bulk-delete customers. Required body:ids(array of customer IDs to delete). Does NOT accept query-style filters...gorgias-pp-cli customers get— Fetch a single customer byid, including their channels (email, phone, social handles),datablob, and...gorgias-pp-cli customers list— List customers with pagination and optional filter params (email,external_id,name,language,...gorgias-pp-cli customers merge— Merge one customer into another. Required query params:source_id(the duplicate, will be merged in and deleted)...gorgias-pp-cli customers update— Update a customer (id) — change name, add/remove channels, edit external IDs, or overwrite top-level fields. Use...
events — Audit log of who-changed-what across tickets, customers, settings
gorgias-pp-cli events get— Retrieve a single audit event byid— captures who/what/when on ticket, customer, or settings mutations. Use to...gorgias-pp-cli events list— List audit events. Documented filters:object_type(e.g. Ticket/Customer/User),object_id,user_ids(actor),...
gorgias-jobs — Schedule and track async Gorgias jobs (bulk exports, macro applies)
gorgias-pp-cli gorgias-jobs create— Kick off an asynchronous Gorgias job. Required body:type(enum: applyMacro, deleteTicket, exportTicket,...gorgias-pp-cli gorgias-jobs delete— Delete a job record byid. Useful for cleaning up completed or failed entries from listings; does not cancel an...gorgias-pp-cli gorgias-jobs get— Fetch a single async job (id) with its status, progress, params, and result/error fields. The polling endpoint...gorgias-pp-cli gorgias-jobs list— List async jobs with filters by type, status, and datetime. Use to find a recent export job by an agent or to...gorgias-pp-cli gorgias-jobs update— Update an async job (id) — typically to cancel it or adjust metadata. Reach for this only when you need to abort...
integrations — Install and configure third-party integrations (Shopify, SMS, social)
gorgias-pp-cli integrations create— Install a new third-party integration on the Gorgias account (Shopify, Instagram, SMS provider, etc.). Passtype...gorgias-pp-cli integrations delete— Uninstall an integration byid. Destructive — disconnects the channel and may stop syncing orders/messages from...gorgias-pp-cli integrations get— Fetch a single integration (id) including its type, status, last-sync time, and provider-specific config. Use to...gorgias-pp-cli integrations list— List all installed integrations on the account — Shopify, Magento, Facebook, voice, etc. Use to discover what...gorgias-pp-cli integrations update— Update an integration's config (id) — refresh credentials, toggle sync features, or rename. Reach for this when...
macros — Reusable canned-reply templates with variables and actions
gorgias-pp-cli macros archive— Archive one or more macros (soft delete) — pass macro IDs in the body. Use this rather thanmacros_deleteto...gorgias-pp-cli macros create— Create a new macro: a reusable reply/action template. Required body:name. Optional:intent,language,...gorgias-pp-cli macros delete— Delete a macro byid. Hard-deletes it from the macro library. Prefermacros_archivefor soft removal so...gorgias-pp-cli macros get— Fetch a single macro byid, returning its body, actions, and variable definitions. Use before applying a macro so...gorgias-pp-cli macros list— List all macros, with optional filters (archived, name). The agent's discovery endpoint for available canned replies...gorgias-pp-cli macros unarchive— Unarchive one or more macros, restoring them to the active library. Pass macro IDs in the body. The companion to...gorgias-pp-cli macros update— Update a macro (id) — edit its body, variables, tags-to-add, or action list. Use when an agent is refining a...
messages — Read messages across tickets (account-wide listing)
gorgias-pp-cli messages— List messages account-wide, paginated. Supported filters areticket_idonly (pluscursor,limit,order_by);...
phone — Voice calls, call events, and recorded audio
gorgias-pp-cli phone call-events-get— Fetch a single voice-call event byid— events capture call lifecycle (ringing, answered, hung-up, transferred)....gorgias-pp-cli phone call-events-list— List voice-call lifecycle events. Documented filter iscall_idonly (pluscursor,limit). Use to inspect the...gorgias-pp-cli phone call-recordings-delete— Delete a stored voice-call recording byid. Use to honor a customer privacy/erasure request or to scrub a test...gorgias-pp-cli phone call-recordings-get— Fetch metadata for a single call recording (id) — duration, URL, related call/ticket. Pair with...gorgias-pp-cli phone call-recordings-list— List voice-call recordings. Documented filter iscall_idonly (pluscursor,limit). Use to find the...gorgias-pp-cli phone calls-get— Fetch a single voice call (id) with direction, status, duration, participants, and the linked ticket. Use when an...gorgias-pp-cli phone calls-list— List voice calls, paginated. Documented filter isticket_idonly (pluscursor,limit,order_by). Use to...
pickups — Delete pickup logistics records (single destructive endpoint)
gorgias-pp-cli pickups <id>— Delete a pickup record byid. Counterpart topickups_create_pickups; use to cancel or remove a stale logistics...
reporting — Run a Gorgias analytics query (POST /reporting/stats)
gorgias-pp-cli reporting— Run a Gorgias analytics query: POST a JSON body withmetric,dimensions,filters, and aperiod. The single...
rules — Automation rules: route, tag, auto-reply, escalate on incoming tickets
gorgias-pp-cli rules create— Create a new automation rule. Required body:nameandcode(the rule logic written as JavaScript). Optional:...gorgias-pp-cli rules delete— Delete an automation rule byid. Stops the rule from firing on future tickets but does not undo past actions. Use...gorgias-pp-cli rules get— Fetch a single automation rule (id) with its full conditions/actions tree and enabled state. Use to inspect why a...gorgias-pp-cli rules list— List all automation rules with their order, enabled state, and summary. The agent's map of what automations are...gorgias-pp-cli rules set-priorities— Set the execution priorities of automation rules. Required body:priorities— an array of objects mapping rule...gorgias-pp-cli rules update— Update an automation rule (id) — edit conditions, actions, or enabled flag. Use to tune an existing workflow...
satisfaction-surveys — CSAT survey definitions and customer ratings/comments
gorgias-pp-cli satisfaction-surveys create— Create a satisfaction-survey instance attached to one ticket and customer. Required body:customer_id,...gorgias-pp-cli satisfaction-surveys get— Fetch a single satisfaction-survey instance byid— the linked ticket/customer, score, customer comment, and...gorgias-pp-cli satisfaction-surveys list— List satisfaction-survey instances (each one tied to a single ticket). Filter withticket_idto fetch the survey...gorgias-pp-cli satisfaction-surveys update— Update a satisfaction-survey instance (id) — typically to record/correct the customer'sscore(1–5),...
tags — Ticket tags — the labels that drive routing rules and reporting
gorgias-pp-cli tags create— Create a new tag in the account's tag library. Body:name(required, max 256 chars, case-sensitive),description...gorgias-pp-cli tags delete— Delete a tag byid. Removes it from the library and unassociates it from every ticket/customer that carries it....gorgias-pp-cli tags delete-all— Bulk-delete tags. Required body:ids(array of tag IDs, min 1). Tags currently referenced by macros or rules...gorgias-pp-cli tags get— Fetch a single tag (id) with its name, decoration, and metadata. Use to verify a tag exists before applying it, or...gorgias-pp-cli tags list— List all tags in the account, optionally filtered by name. The agent's lookup endpoint for finding the right...gorgias-pp-cli tags merge— Merge other tags INTO this tag — path{id}is the destination (surviving) tag, and the body field...gorgias-pp-cli tags update— Update a tag (id) — rename it or change its color/decoration. Affects every record currently carrying the tag,...
teams — Agent teams: how tickets are grouped and routed for assignment
gorgias-pp-cli teams create— Create a new team (group of agents) in the account. Passnameand optionally members. Use when organizing routing...gorgias-pp-cli teams delete— Delete a team byid. Removes it from routing rules and views; members remain but lose the team grouping. Use when...gorgias-pp-cli teams get— Fetch a single team (id) with its members and metadata. Use when an agent needs to know who's on a team before...gorgias-pp-cli teams list— List all teams in the account. The agent's lookup for valid team IDs/names when assigning a ticket, routing via a...gorgias-pp-cli teams update— Update a team (id) — rename it or change its membership. Use to reorganize agents or correct a misconfigured team.
ticket-search — Search across tickets, customers, messages, etc.
gorgias-pp-cli ticket-search— Full-text search across Gorgias tickets, customers, and messages. POST a JSON body withquery,resource_type,...
tickets — Read and write Gorgias tickets, messages, and tag assignments
gorgias-pp-cli tickets create— Create a new ticket. Body specifieschannel,via,subject, an initialmessagesarray, the customer, and...gorgias-pp-cli tickets custom-fields-list— List every custom field value on ticket (id). Use to read structured metadata an agent or integration attached...gorgias-pp-cli tickets custom-fields-set— Set a single custom field value on a ticket: first{id}is the ticket, second{id}is the custom field. Use to...gorgias-pp-cli tickets custom-fields-set-all— Bulk-set custom field values on ticket (id) — pass an array of field/value pairs. Preferred when an agent needs...gorgias-pp-cli tickets custom-fields-unset— Clear a custom field value on a ticket: first{id}is the ticket, second{id}is the custom field. Unsets (does...gorgias-pp-cli tickets delete— Delete a ticket byid. Hard-deletes the conversation and its messages — reserve for GDPR erasure, spam, or...gorgias-pp-cli tickets get— Fetch a single ticket byidwith status, channel, assignee, customer, tags, and summary fields. Use after...gorgias-pp-cli tickets list— List tickets with filters (status, assignee, customer, channel, datetime, tag). The agent's primary endpoint for...gorgias-pp-cli tickets messages-create— Post a new message on ticket (id) — used to reply to the customer or write an internal note. The body...gorgias-pp-cli tickets messages-delete— Delete a message from a ticket: first{id}is the ticket, second{id}is the message. Use sparingly —...gorgias-pp-cli tickets messages-get— Fetch a single message: first{id}is the ticket, second{id}is the message. Use to load full body and...gorgias-pp-cli tickets messages-list— List all messages on ticket (id) in chronological order — both customer-sent and agent-sent, public and internal...gorgias-pp-cli tickets messages-update— Update a message: first{id}is the ticket, second{id}is the message. Typically used to edit an internal...gorgias-pp-cli tickets tags-add— Add one or more tags to ticket (id). The body shape (tag IDs vs names; whether unknown names auto-create) is not...gorgias-pp-cli tickets tags-list— List the tags currently attached to ticket (id). Use to read the ticket's categorization before deciding what...gorgias-pp-cli tickets tags-remove— Remove tags from ticket (id). Pass the tag IDs/names to detach. Use when re-categorizing a ticket or undoing an...gorgias-pp-cli tickets tags-replace— Replace ticket (id)'s entire tag set with the supplied list. Use for full re-tagging; for additive/subtractive...gorgias-pp-cli tickets update— Update a ticket (id) — change status (open/closed/resolved), assignee, priority, subject, orvia. The...
users — Agents and admin users on the Gorgias account
gorgias-pp-cli users create— Create a new user (Gorgias agent/operator). Pass name, email, role, and optionally team memberships. Use when...gorgias-pp-cli users delete— Delete a user (id) — deactivates the agent account and removes them from routing. Their historical ticket...gorgias-pp-cli users get— Fetch a single user (id) — agent name, email, role, teams, status. Use to look up who an assignee is or to...gorgias-pp-cli users list— List users (Gorgias agents/operators) on the account, with filters for role, status, and team. The agent's lookup...gorgias-pp-cli users update— Update a user (id) — change role, name, team membership, or active state. Use for admin operations like...
views — Saved Gorgias inbox views (named filters used by agents)
gorgias-pp-cli views create— Create a saved view — a filtered ticket list (e.g. 'My open tickets', 'Urgent + unassigned') defined by...gorgias-pp-cli views delete— Delete a saved view byid. Removes it from the sidebar for everyone who saw it. Use when retiring stale filters.gorgias-pp-cli views get— Fetch a single saved view (id) with its filter definition and metadata. Use to introspect what conditions a view...gorgias-pp-cli views items-list— Return the ticket items currently matching saved view (id). Required:id(path). Optional:cursor,direction...gorgias-pp-cli views items-update— Update the materialized items of a view (id) — used to reorder, bulk-mutate, or refresh the cached set depending...gorgias-pp-cli views list— List all saved views on the account, including ownership and visibility. The agent's catalogue of pre-built ticket...gorgias-pp-cli views update— Update a saved view (id) — change its filter criteria, name, or sharing. Use to evolve a view's definition as...
widgets — Configure on-site chat/contact widget instances
gorgias-pp-cli widgets create— Create a new agent-facing sidebar widget shown inside the Gorgias helpdesk (on ticket, customer, or user views —...gorgias-pp-cli widgets delete— Delete a sidebar widget config byid. After deletion the widget stops rendering in the helpdesk UI on the...gorgias-pp-cli widgets get— Fetch a single sidebar widget (id) with itscontext(ticket/customer/user),template(data source), order, and...gorgias-pp-cli widgets list— List all agent-facing sidebar widgets on the account, optionally filtered byintegration_idorapp_id. Use to...gorgias-pp-cli widgets update— Update a sidebar widget (id) — typically to change itstemplate(data source),order(display position),...
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
gorgias-pp-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.
Recipes
Sync recent tickets to a local SQLite mirror
gorgias-pp-cli sync --resources tickets --since 7d
Hydrates the local DB so subsequent searches and analytics run offline against a recent snapshot instead of hitting the API on every call.
For tickets, --since is implemented as documented newest-first ordering plus a local cutoff. A live test on May 23, 2026 showed updated_datetime__gte returns HTTP 400 Unknown field, so agents should not try to "repair" ticket sync with that parameter.
Full-text search across synced tickets
gorgias-pp-cli search 'refund cancellation' --limit 10 --agent
Searches the local SQLite mirror for tickets matching the query — much faster than the live API for repeated lookups.
Stream live ticket changes
gorgias-pp-cli tail --interval 30s --agent
Polls the API on the given interval and emits one JSON line per new or updated ticket — useful for triage agents that should react to changes.
Find tickets with no assignee
gorgias-pp-cli orphans --agent
Lists items missing key fields like assignee or project — the standard 'unowned work' query for support leads.
Find stale tickets
gorgias-pp-cli stale --days 7 --agent
Lists items with no updates in the last 7 days. Pairs well with orphans for an oncall review.
Run a compound workflow
gorgias-pp-cli workflow --agent
Lists available compound workflows that combine multiple API operations into one bounded payload.
Auth Setup
Gorgias uses HTTP Basic auth — your account email as username and an API key from Settings → Account → REST API as password. Set GORGIAS_USERNAME, GORGIAS_API_KEY, and GORGIAS_BASE_URL (https://.gorgias.com/api). How those env vars get into the process is up to you — a shell profile, a secrets manager, a CI secret store; the CLI doesn't care.
Run gorgias-pp-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
Pipeable — JSON on stdout, errors on stderr
Filterable —
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:gorgias-pp-cli account get --agent --select id,name,statusPreviewable —
--dry-runshows the request without sendingOffline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
Error envelope
Under --json (or --agent), failures emit a single JSON document on stderr:
{"error": {"message": "<human-readable cause>", "exit_code": <int>}}
Exit codes match the table in Exit Codes below. Commands that
naturally carry status in their own JSON body (e.g. doctor --json) embed
the failure inside the report instead, and stderr is empty — jq always sees
a single JSON document per stream.
Configuration discovery
In addition to GORGIAS_USERNAME, GORGIAS_API_KEY, and GORGIAS_BASE_URL, the
CLI honors GORGIAS_CONFIG (path to a TOML config file, default
$XDG_CONFIG_HOME/gorgias-pp-cli/config.toml) and the standard XDG variables
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME. On Windows, the CLI falls
back to os.UserConfigDir() / os.UserCacheDir() (%APPDATA%,
%LOCALAPPDATA%) when the XDG vars are unset.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
gorgias-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
gorgias-pp-cli feedback --stdin < notes.txt
gorgias-pp-cli feedback list --json --limit 10
Entries are stored locally at ~/.gorgias-pp-cli/feedback.jsonl. They are never POSTed unless GORGIAS_FEEDBACK_ENDPOINT is set AND either --send is passed or GORGIAS_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout |
Default; write to stdout only |
file:<path> |
Atomically write output to <path> (tmp + rename) |
webhook:<url> |
POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration
gorgias-pp-cli profile save briefing --json
gorgias-pp-cli --profile briefing account get
gorgias-pp-cli profile list --json
gorgias-pp-cli profile show briefing
gorgias-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or--help→ showgorgias-pp-cli --helpoutput - Starts with
install→ ends withmcp→ MCP installation; otherwise → see Prerequisites above - Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
claude mcp add gorgias-pp-mcp -- gorgias-pp-mcp
Verify: claude mcp list
Direct Use
- Check if installed:
which gorgias-pp-cliIf not found, offer to install (see Prerequisites at the top of this skill). - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agentflag:gorgias-pp-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help:
gorgias-pp-cli <command> --help.