pp-gorgias

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/sales-and-crm/gorgias/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# 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:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install gorgias --cli-only
   ```
2. Verify: `gorgias-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for 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.3 or newer):

```bash
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 reports `credentials: valid` only when an authenticated call succeeds.

  _Saves the first-five-minutes credential-debug cycle when wiring up an agent._

  ```bash
  gorgias-pp-cli doctor --json
  ```
- **`gorgias-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 `--since` uses documented `order_by=updated_datetime:desc` plus local filtering; do not add undocumented filters like `updated_datetime__gte` unless Gorgias documents them and a live smoke confirms them._

  ```bash
  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 by `id`. 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 supported `object_type` values). Required body:...
- `gorgias-pp-cli custom-fields get` — Fetch a single custom field definition by `id`, returning its data type, label, target object, and option list. Use...
- `gorgias-pp-cli custom-fields list` — List custom field definitions for a single `object_type` (`Ticket` or `Customer` — REQUIRED query param)....
- `gorgias-pp-cli custom-fields update` — Update one custom field definition by `id` — 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. Pass `name`, `email`, optional `channels` (email/phone/social handles), and `data` for...
- `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's `data` blob (`id` in path). Body: `data` (required) plus optional `version` for last-write-wins...
- `gorgias-pp-cli customers delete` — Delete one customer by `id`. 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 by `id`, including their channels (email, phone, social handles), `data` blob, 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 by `id` — 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 by `id`. 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.). Pass `type`...
- `gorgias-pp-cli integrations delete` — Uninstall an integration by `id`. Destructive — disconnects the channel and may stop syncing orders/messages from...
- `gorgia