CLI for the HelpScout API. Manage conversations, customers, mailboxes, knowledge base articles, and more from the terminal. Covers both Inbox and Docs APIs w...
Use hs to interact with HelpScout from the terminal. Two API namespaces: hs inbox (Mailbox API — conversations, customers, users, teams, etc.) and hs docs (Docs API — sites, collections, categories, articles).
Inbox uses OAuth2 client credentials (App ID + App Secret). Docs uses an API key.
hs inbox auth login — interactive setup, validates against the APIhs docs auth login — prompt for Docs API key, validateshs inbox auth status / hs docs auth status — check stored credentialshs inbox auth logout / hs docs auth logout — remove credentialsCredential resolution order: OS keyring → config file. For non-interactive auth, use hs inbox config set --inbox-app-id <id> --inbox-app-secret <secret>.
conv)hs inbox conv list --status active --mailbox <id> --tag <name> --assigned-to <uid> --embed threadshs inbox conv get <id> --embed threadshs inbox conv create --mailbox <id> --subject "..." --customer <email> --body "..."hs inbox conv update <id> --status closed --subject "..."hs inbox conv delete <id>hs inbox conv threads list <conv-id>hs inbox conv threads reply <conv-id> --customer <email> --body "..." --status closedhs inbox conv threads note <conv-id> --body "..."hs inbox conv tags set <conv-id> --tag billing --tag urgenths inbox conv fields set <conv-id> --field <id>=<value>hs inbox conv attachments upload <conv-id> --thread-id <id> --file ./pathcust)hs inbox cust list --query "email:jane@example.com"hs inbox cust get <id>hs inbox cust create --first-name Jane --last-name Doe --email jane@example.comhs inbox cust update <id> --last-name Smithhs inbox cust delete <id>mb)hs inbox mb list / hs inbox mb get <id>hs inbox mb folders list <mb-id> / hs inbox mb custom-fields list <mb-id>hs inbox users list --email user@co.com / hs inbox users get <id> / hs inbox users mehs inbox users status get <uid> / hs inbox users status set <uid> --status awayhs inbox teams list / hs inbox teams members <team-id>hs inbox organizations list --query "acme" / hs inbox organizations get <id>hs inbox organizations create --name "Acme Corp" / hs inbox organizations delete <id>hs inbox tags list / hs inbox ratings listwf)hs inbox wf list / hs inbox wf run <id> --conversation-ids id1,id2hs inbox wf update-status <id> --status activewh)hs inbox wh list / hs inbox wh get <id>hs inbox wh create --url https://... --events convo.created --secret s3creths inbox wh delete <id>hs inbox saved-replies list --mailbox-id <id>hs inbox saved-replies create --mailbox-id <id> --name "Greeting" --body "Hello..."hs inbox reports conversations --start 2025-01-01 --end 2025-01-31 --mailbox <id>chats, company, conversations, customers, docs, email, productivity, ratings, usershs inbox tools briefing — daily briefing summaryhs inbox tools briefing --assigned-to <uid> --embed threads — agent-specific briefing with thread contenths docs sites list / hs docs sites get <id>hs docs sites create --subdomain help --title "Help Center"hs docs collections list --site <id> / hs docs collections get <id>hs docs collections create --site <id> --name "Getting Started"hs docs categories list <collection-id> / hs docs categories get <id>hs docs categories create --collection <id> --name "FAQ"hs docs categories reorder <collection-id> --categories id1,id2,id3hs docs articles list --collection <id> or --category <id>hs docs articles search --query "password reset" --site <id>hs docs articles get <id> / hs docs articles get <id> --drafths docs articles create --collection <id> --name "How to reset" --text "Step 1..."hs docs articles update <id> --text "Updated..." --status publishedhs docs articles delete <id>hs docs articles draft save <id> --text "..." / hs docs articles draft delete <id>hs docs articles revisions list <id> / hs docs articles revisions get <id> <rev-id>hs docs articles upload <id> --file ./image.pnghs docs redirects list <site-id> / hs docs redirects find --site <id> --url /old-pathhs docs redirects create --site <id> --url-mapping /old --redirect /newhs docs assets article upload --file ./img.pnghs docs assets settings upload --file ./logo.png--format table|json|json-full|csv — output format (default: table)--no-paginate — fetch all pages automatically--page <n> / --per-page <n> — pagination (defaults: 1, 25)--debug — show HTTP request/response detailshs config set --format json --inbox-default-mailbox 12345hs config get [key] — print one or all config valueshs config path — print config file location~/.config/hs/config.yaml (Linux/macOS), %AppData%\hs\config.yaml (Windows)Inbox commands redact customer/user PII with deterministic fake identities. Controlled via config key inbox_pii_mode.
| Mode | Effect |
|---|---|
off | No redaction (default) |
customers | Redact customer names, emails, phones |
all | Redact both customers and users |
--unredacted flag on hs inbox disables redaction for one call (requires inbox_pii_allow_unredacted: true in config)Allowlist model — restrict which commands an agent can run. Empty policy = unrestricted.
inbox_permissions / docs_permissions — comma-separated resource:operation pairs*:read, conversations:*read, write, delete, *hs inbox permissions — inspect current policy, shows ALLOW/DENY per commandExample: hs inbox config set --inbox-permissions "conversations:read,customers:read,mailboxes:read"
hs updatehs completion bash|zsh|fish|powershellZIP package — ready to use