hscli

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/

Install

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.

Quick start

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 mutations

For CI/CD, use the non-interactive client-credentials flow:

HSCLI_APP_ID=... HSCLI_APP_SECRET=... hscli auth login --client-credentials

Commands

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.

Documentation

• 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

Contributing

See CONTRIBUTING.md. Security issues: see SECURITY.md.

License

MIT © Eric Rodriguez