Agent & workflow ready
JSON output, deterministic exit codes, and a raw hscli api hatch let agents and pipelines drive Help Scout directly.
Open source · Help Scout CLI Help Scout,
Help Scout,
from your terminal.
A fast, scriptable CLI for Help Scout — built for terminals, CI pipelines, and AI agents like Claude Code and Codex. Every command speaks JSON and returns clean exit codes.
$npm i -g @wavyx/hscli
$ hscli conv list --status active --output table
ID SUBJECT CUSTOMER STATUS
4831 Refund for order #2207 amir@acme.io active
4830 Can't reset my password lou@hey.com active
4827 Invoice question kai@studio.co active
$ # close everything tagged "resolved"
$ hscli conv bulk-status --status active --tag resolved \
--set closed --yes
✓ 12 conversations closed · exit 0
Why hscli
Built for automation, not clicking.
Four design decisions that make hscli safe to hand to a script — or an agent.
Pipe-friendly output
Every command supports --output table|json|yaml|csv, plus --jq and --fields for inline filtering and projection.
Secure by default
OAuth tokens live only in your OS keychain — never written to disk in plaintext. hscli api is locked to the Help Scout host.
Full account backups
hscli backup dumps your whole account to JSON with incremental refresh, resume, deletion detection, and attachments.
What you can actually do
Real work, one line at a time.
hscli composes with the tools you already use — jq, xargs, cron, and your CI runner.
Triage
Let an agent clear the queue
Pipe active conversations into your model and act on its decisions — no integration code.
$ hscli conv list --status active \
--output json --fields id,subject \
| claude -p "tag & assign each"
Backup
Nightly account snapshot in CI
Incremental by default, resumable, and deletion-aware. Drop it in a cron job or a GitHub Action.
# .github/workflows/backup.yml
$ hscli backup --out ./hs-data \
--attachments --compress
✓ 4,210 convs · 38 MB · exit 0
Report
Pull metrics into your stack
Stream any report as JSON straight into a notebook, your BI tool, or a jq pipeline.
$ hscli report conversations \
--start 2026-05-01 --end 2026-05-31 \
--output json > may.json
MCP
Plug hscli into any agent
Run hscli as a Model Context Protocol server and Claude — Desktop, Code, or any MCP client — gets one typed tool per command. Reads by default; --allow-writes lets the agent act.
# one line — Claude Code now has hscli as native tools
$ claude mcp add hscli -- hscli mcp serve
✓ hscli connected · 47 read-only tools
$ claude -p "triage today's billing tickets"
→ conv_list · conv_get · structured JSON · exit 0
Docs
Let an agent keep your help center current
Point a model at last week's inbox, let it spot the most-asked question, and publish the answer straight to your Docs knowledge base — version-controlled and shipped from CI.
Docs knowledge base →# nightly — turn last week's repeat questions into a Docs article
$ hscli conv list --tag question --since 7d --output json \
| claude -p "draft a KB article for the top question" > article.html
$ hscli docs article create --collection "$KB" \
--name "Resetting your password" --text @article.html --status published
✓ article published · exit 0
Install
Get it your way.
npm is the source of truth — Homebrew, Scoop, and Docker track every release.
npmany OS · Node 20+
$npm i -g @wavyx/hscli
HomebrewmacOS · Linux
$brew install wavyx/tap/hscli
ScoopWindows
$scoop install hscli
Dockerno local Node
$docker run ghcr.io/wavyx/hscli
Then authenticate and run hscli conv list — or see the installation guide.
Drive Help Scout from anywhere.
Install once. Script everything. Hand the rest to an agent.