Help Scout

---

name: hs description: CLI for the HelpScout API. Manage conversations, customers, mailboxes, knowledge base articles, and more from the terminal. Covers both Inbox and Docs APIs with full CRUD, PII redaction, permissions, and multiple output formats. homepage: https://github.com/operator-kit/hs-cli metadata: {"clawdbot":{"emoji":"📬","requires":{"bins":["hs"]},"install":[{"id":"brew","kind":"brew","formula":"operator-kit/tap/hs","bins":["hs"],"label":"Install hs (brew)"}]}}

---

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.

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

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

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)

Self-update: hs update

Shell completions: hs completion bash|zsh|fish|powershell