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 <id> --inbox-app-secret <secret>.

Inbox commands

Conversations (conv)

• hs inbox conv list --status active --mailbox <id> --tag <name> --assigned-to <uid> --embed threads
• hs inbox conv get <id> --embed threads
• hs 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 closed
• hs inbox conv threads note <conv-id> --body "..."
• hs inbox conv tags set <conv-id> --tag billing --tag urgent
• hs inbox conv fields set <conv-id> --field <id>=<value>
• hs inbox conv attachments upload <conv-id> --thread-id <id> --file ./path

Customers (cust)

• 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.com
• hs inbox cust update <id> --last-name Smith
• hs inbox cust delete <id>

Mailboxes (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>

Users

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

Teams

• hs inbox teams list / hs inbox teams members <team-id>

Organizations

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

Tags / Ratings

• hs inbox tags list / hs inbox ratings list

Workflows (wf)

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

Webhooks (wh)

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

Saved replies

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

Reports

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

Tools

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

Docs commands

Sites

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

Collections

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

Categories

• 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,id3

Articles

• hs 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> --draft
• hs docs articles create --collection <id> --name "How to reset" --text "Step 1..."
• hs docs articles update <id> --text "Updated..." --status published
• hs 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.png

Redirects

• hs docs redirects list <site-id> / hs docs redirects find --site <id> --url /old-path
• hs docs redirects create --site <id> --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 <n> / --per-page <n> — 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