hs

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).

Auth

Inbox uses OAuth2 client credentials (App ID + App Secret). Docs uses an API key.

• hs inbox auth login — interactive setup, validates against the API
• hs docs auth login — prompt for Docs API key, validates
• hs inbox auth status / hs docs auth status — check stored credentials
• hs inbox auth logout / hs docs auth logout — remove credentials

Credential resolution order: OS keyring → config file. For non-interactive auth, use hs inbox config set --inbox-app-id --inbox-app-secret .

Inbox commands

Conversations (conv)

• hs inbox conv list --status active --mailbox --tag --assigned-to --embed threads
• hs inbox conv get --embed threads
• hs inbox conv create --mailbox --subject "..." --customer --body "..."
• hs inbox conv update --status closed --subject "..."
• hs inbox conv delete
• hs inbox conv threads list
• hs inbox conv threads reply --customer --body "..." --status closed
• hs inbox conv threads note --body "..."
• hs inbox conv tags set --tag billing --tag urgent
• hs inbox conv fields set --field =
• hs inbox conv attachments upload --thread-id --file ./path

Customers (cust)

• hs inbox cust list --query "email:jane@example.com"
• hs inbox cust get
• hs inbox cust create --first-name Jane --last-name Doe --email jane@example.com
• hs inbox cust update --last-name Smith
• hs inbox cust delete

Mailboxes (mb)

• hs inbox mb list / hs inbox mb get
• hs inbox mb folders list / hs inbox mb custom-fields list

Users

• hs inbox users list --email user@co.com / hs inbox users get / hs inbox users me
• hs inbox users status get / hs inbox users status set --status away

Teams

• hs inbox teams list / hs inbox teams members

Organizations

• hs inbox organizations list --query "acme" / hs inbox organizations get
• hs inbox organizations create --name "Acme Corp" / hs inbox organizations delete

Tags / Ratings

• hs inbox tags list / hs inbox ratings list

Workflows (wf)

• hs inbox wf list / hs inbox wf run --conversation-ids id1,id2
• hs inbox wf update-status --status active

Webhooks (wh)

• hs inbox wh list / hs inbox wh get
• hs inbox wh create --url https://... --events convo.created --secret s3cret
• hs inbox wh delete

Saved replies

• hs inbox saved-replies list --mailbox-id
• hs inbox saved-replies create --mailbox-id --name "Greeting" --body "Hello..."

Reports

• hs inbox reports conversations --start 2025-01-01 --end 2025-01-31 --mailbox
• Subcommands: chats, company, conversations, customers, docs, email, productivity, ratings, users

Tools

• hs inbox tools briefing — daily briefing summary
• hs inbox tools briefing --assigned-to --embed threads — agent-specific briefing with thread content

Docs commands

Sites

• hs docs sites list / hs docs sites get
• hs docs sites create --subdomain help --title "Help Center"

Collections

• hs docs collections list --site / hs docs collections get
• hs docs collections create --site --name "Getting Started"

Categories

• hs docs categories list / hs docs categories get
• hs docs categories create --collection --name "FAQ"
• hs docs categories reorder --categories id1,id2,id3

Articles

• hs docs articles list --collection or --category
• hs docs articles search --query "password reset" --site
• hs docs articles get / hs docs articles get --draft
• hs docs articles create --collection --name "How to reset" --text "Step 1..."
• hs docs articles update --text "Updated..." --status published
• hs docs articles delete
• hs docs articles draft save --text "..." / hs docs articles draft delete
• hs docs articles revisions list / hs docs articles revisions get
• hs docs articles upload --file ./image.png

Redirects

• hs docs redirects list / hs docs redirects find --site --url /old-path
• hs docs redirects create --site --url-mapping /old --redirect /new

Assets

• hs docs assets article upload --file ./img.png
• hs docs assets settings upload --file ./logo.png

Output & global flags

• --format table|json|json-full|csv — output format (default: table)
• --no-paginate — fetch all pages automatically
• --page / --per-page — pagination (defaults: 1, 25)
• --debug — show HTTP request/response details

Config

• hs config set --format json --inbox-default-mailbox 12345
• hs config get [key] — print one or all config values
• hs config path — print config file location
• Default location: ~/.config/hs/config.yaml (Linux/macOS), %AppData%\hs\config.yaml (Windows)

PII redaction

Inbox commands redact customer/user PII with deterministic fake identities. Controlled via config key inbox_pii_mode.

• --unredacted flag on hs inbox disables redaction for one call (requires inbox_pii_allow_unredacted: true in config)

Permissions

Allowlist model — restrict which commands an agent can run. Empty policy = unrestricted.

• Set via config key inbox_permissions / docs_permissions — comma-separated resource:operation pairs
• Wildcards: :read, conversations:
• Operations: read, write, delete, *
• hs inbox permissions — inspect current policy, shows ALLOW/DENY per command

Example: hs inbox config set --inbox-permissions "conversations:read,customers:read,mailboxes:read"

Notes

• Self-update: hs update
• Shell completions: hs completion bash|zsh|fish|powershell