Command-line interface for Help Scout.
Covers the Mailbox API 2.0 (conversations, customers, mailboxes, users, tags, workflows, webhooks, reports) and the Docs API (knowledge base: sites, collections, categories, articles, search), plus Beacon HMAC/snippet utilities and a full account backup.
JSON output, deterministic exit codes, and a raw hscli api escape hatch make it
a clean way to drive Help Scout from CI pipelines and AI agents (Claude Code,
Codex, and similar) — no SDK glue required.
📖 Documentation:https://wavyx.github.io/hscli/
npm install -g @wavyx/hscli # npm (Node.js 20+)
brew tap wavyx/tap && brew install hscli # Homebrew (macOS/Linux)
scoop bucket add hscli https://github.com/wavyx/scoop-hscli && scoop install hscli # Scoop (Windows)
docker run --rm ghcr.io/wavyx/hscli --help # Docker (no local Node)The binary is hscli. The Docker image has no OS keychain, so use it for Docs
(HSCLI_DOCS_API_KEY), api, and stateless utilities rather than Mailbox OAuth.
Credential storage: hscli stores OAuth tokens only in your operating system keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux). It will not write credentials to disk in plaintext — if no keychain is available, authentication fails by design.
You bring your own Help Scout OAuth app (Help Scout apps are account-scoped, so
there is no shared app). The hscli auth setup wizard walks you through creating
one.
hscli auth setup # Configure your OAuth app (one-time)
hscli auth login # Authenticate (opens browser)
hscli conv list # List conversations
hscli conv reply 123 --body "Thanks"# Reply to a conversation
hscli customer create --email user@example.com --first Jane
hscli backup --out ~/hs-backup # Full account backup (incremental on re-run)# Docs knowledge base (separate per-user API key: `hscli docs auth` or HSCLI_DOCS_API_KEY)
hscli docs auth # Store your Docs API key in the keychain
hscli docs article search "refund"# Search the knowledge base# Run as an MCP server so AI agents call hscli as native tools (read-only by default)
hscli mcp serve # add --allow-writes to expose mutationsFor CI/CD, use the non-interactive client-credentials flow:
HSCLI_APP_ID=... HSCLI_APP_SECRET=... hscli auth login --client-credentials| Topic | Commands |
|---|---|
hscli auth | setup, login, logout, status, refresh |
hscli conv | list, get, create, reply, note, status, assign, tag, move, delete, threads, edit-note, dump, export, search, watch, count, attachments, bulk-status |
hscli mailbox | list, get, folders, fields |
hscli customer | create, update, list, get, search, conversations |
hscli user | me, list, get |
hscli tag | list, get, usage |
hscli workflow | list, run |
hscli webhook | list, get, create, delete |
hscli report | company, user, conversations, beacon |
hscli beacon | sign, verify, embed, identify-snippet — HMAC + snippet utilities for Beacon Secure Mode |
hscli docs | auth, site, collection, category, article — read/search + full CRUD on collections, categories & articles (incl. drafts) in the Docs knowledge base (separate per-user API key) |
hscli profile | list, use, current |
hscli config | get, set, list, validate |
hscli alias | set, list, unset — custom command shortcuts |
hscli backup | Full account dump with incremental refresh, resume, deletion detection, attachments |
hscli api | Raw API escape hatch: hscli api GET /v2/conversations (locked to api.helpscout.net) |
hscli mcp | serve — run hscli as an MCP server so AI agents call commands as tools (read-only by default; --allow-writes to enable mutations) |
hscli doctor | Diagnostic checks |
hscli version | Version info |
Run hscli --help or hscli <topic> --help for details. Every list/get command
supports --output table|json|yaml|csv, --jq, and --fields.
- Authentication — setup, login, profiles, CI/CD
- Commands — full command reference
- Configuration — env vars, profiles, settings
- API Reference — Help Scout endpoints used
- Backup & Data Portability —
hscli backup,hscli conv dump,hscli conv export --embed - Beacon — Beacon Secure Mode HMAC signing, embed/identify snippets, source-based reporting, limitations
See CONTRIBUTING.md. Security issues: see SECURITY.md.
MIT © Eric Rodriguez