Command reference

Every command follows the same grammar:

hscli <group> <action> [target] [flags]

Run hscli <group> --help for the live, self-describing version of any command. This page lists all 89 commands in hscli v0.11.2.

alias

shortcuts

Define shortcuts for commands you run often.

Command	Description	Key flags
alias list	List all configured aliases	—
alias set <name> <command>	Create or update an alias	—
alias unset <name>	Remove an alias	—

auth

credentials

Authenticate and manage credentials (stored in your OS keychain). See Authentication.

Command	Description	Key flags
auth login	Authenticate with Help Scout	--client-credentials --app-id --app-secret
auth logout	Log out and remove stored credentials	—
auth refresh	Force-refresh the stored access token	—
auth setup	Configure your own Help Scout OAuth app	--app-id --app-secret
auth status	Show current authentication status	—

beacon

beacon

Generate Beacon embeds and sign/verify identity payloads.

Command	Description	Key flags
beacon embed <beaconId>	Generate the <script> embed block to add a Beacon to your website	--color --position --style --text --icon-image
beacon identify-snippet	Generate server-side identify snippet with HMAC signing for node, rails, php, django, python	--beacon-id --secret --stack
beacon sign	Generate Beacon Secure Mode HMAC-SHA256 signature for an email	--email --secret
beacon verify	Verify a Beacon Secure Mode HMAC signature (exit 0 on match, exit 1 on mismatch)	--email --secret --signature

config

settings

Read and write per-profile configuration. See Configuration.

Command	Description	Key flags
config get <key>	Get a config value for the active profile	—
config list	List all config for the active profile	—
config set <key> <value>	Set a config value for the active profile	—
config validate	Validate CLI configuration	—

conv

conversations

List, read, and act on conversations — the workhorse of hscli. See the Conversations guide.

Command	Description	Key flags
conv assign <id>	Assign a conversation to a user	--user
conv attachments <id>	List attachments for a conversation	—
conv bulk-status	Batch change status on multiple conversations	--mailbox --status --tag --set --limit --yes
conv count	Count conversations	--status --mailbox --tag
conv create	Create a new conversation	--mailbox --customer --subject --body --type --tag --assign-to
conv delete <id>	Delete a conversation	--yes
conv dump <id>	Dump a single conversation with threads, customers, tags, and attachment metadata	--out
conv edit-note <id> <threadId>	Edit a note or thread body	--body
conv export	Bulk export conversations	--mailbox --status --since --format --tag --embed --source
conv get <id>	Get a conversation by ID	—
conv list	List conversations	--mailbox --status --tag --assigned-to --query --since --limit --source
conv move <id>	Move a conversation to another mailbox	--to-mailbox
conv note <id>	Add a note to a conversation	--body
conv reply <id>	Reply to a conversation	--body --cc --bcc --draft
conv search <query>	Search conversations	--mailbox --limit
conv status <id>	Change conversation status	--set
conv tag <id>	Update tags on a conversation	--add --remove
conv threads <id>	List threads of a conversation	—
conv watch	Live tail of conversations (poll-based)	--mailbox --status --poll --limit --once --max-polls

customer

people

Search, read, create, and update the people behind your conversations. See the Customers guide.

Command	Description	Key flags
customer conversations <id>	List conversations for a customer	--limit
customer create	Create a new customer	--email --first --last --company --phone --job-title
customer get <id>	Get a customer by ID	—
customer list	List customers	--mailbox --first --last --since --limit
customer search <query>	Search customers	--limit
customer update <id>	Update a customer	--email --first --last --company --phone --job-title

docs

knowledge base

Manage your Help Scout Docs knowledge base — sites, collections, categories, and articles. Uses a separate Docs API key (hscli docs auth). See the Docs guide.

Command	Description	Key flags
docs article create	Create a Docs article	--collection --name --text --status --slug --categories --keywords
docs article delete <id>	Delete a Docs article	--yes
docs article delete-draft <id>	Discard the draft of a Docs article (published text is kept)	--yes
docs article get <id>	Get a Docs article by id or number	—
docs article list	List articles in a Docs collection or category	--collection --category --status --limit
docs article save-draft <id>	Save a draft for a Docs article (does not publish)	--text
docs article search <query>	Search Docs articles by keyword	--collection --site --status --visibility --limit
docs article update <id>	Update a Docs article	--name --text --status --slug
docs auth	Store your Help Scout Docs API key in the OS keychain (separate from Mailbox auth)	--api-key
docs category create	Create a Docs category within a collection	--collection --name --visibility --order
docs category delete <id>	Delete a Docs category	--yes
docs category list <collectionId>	List categories within a Docs collection	--limit
docs category update <id>	Update a Docs category	--name --visibility --order
docs collection create	Create a Docs collection	--site --name --visibility --order
docs collection delete <id>	Delete a Docs collection	--yes
docs collection get <id>	Get a Docs collection by id or number	—
docs collection list	List Docs collections	--limit --site --visibility
docs collection update <id>	Update a Docs collection	--name --visibility --order --site
docs site get <id>	Get a Docs site by id	—
docs site list	List Docs sites	--limit

mailbox

inboxes

Inspect mailboxes, folders, and custom fields.

Command	Description	Key flags
mailbox fields <id>	List custom fields for a mailbox	—
mailbox folders <id>	List folders for a mailbox	—
mailbox get <id>	Get a mailbox by ID	—
mailbox list	List mailboxes	--limit

mcp

AI agents

Run hscli as a Model Context Protocol server so AI agents can call it as native tools. Reads by default; pass --allow-writes to expose mutating tools. See the MCP guide.

Command	Description	Key flags
mcp serve	Run hscli as a Model Context Protocol (MCP) server over stdio	--allow-writes

profile

profiles

Switch between named auth profiles.

Command	Description	Key flags
profile current	Show the active profile	—
profile list	List all configured profiles	—
profile use <name>	Switch the active profile	—

report

metrics

Volume, company, and per-user metrics as JSON, CSV, or a table. See the Reporting guide.

Command	Description	Key flags
report beacon	Aggregate conversation counts by source.type and source.via (derived from Mailbox API; useful for Beacon-origin analysis)	--since --mailbox
report company	Get company report	--start --end --mailbox --tag
report conversations	Get conversations report	--start --end --mailbox --tag
report user	Get user report	--start --end --user

tag

tags

List tags and their usage.

Command	Description	Key flags
tag get <id>	Get a tag by ID	—
tag list	List tags	--limit
tag usage <name>	Show conversation count for a tag	—

user

team

Look up team members and the authenticated user.

Command	Description	Key flags
user get <id>	Get a user by ID	—
user list	List users	--mailbox --email --limit
user me	Get the authenticated user	—

webhook

events

Create, list, and delete webhooks.

Command	Description	Key flags
webhook create	Create a webhook	--url --event --secret --label
webhook delete <id>	Delete a webhook	--yes
webhook get <id>	Get a webhook by ID	—
webhook list	List webhooks	--limit

workflow

automation

List and manually run workflows.

Command	Description	Key flags
workflow list	List workflows	--mailbox --type --limit
workflow run <id>	Run a manual workflow on conversations	--conv

api

escape hatch

Reach any Help Scout endpoint directly — locked to the Help Scout host. See the hscli api reference.

Command	Description	Key flags
api <method> <path>	Make a raw API request	--body --content-type

hscli api GET /v2/mailboxes --jq '.[] | .name'
hscli api POST /v2/conversations/4831/tags --body '{"tags":["vip"]}'

backup

archive

Dump your whole account to JSON with incremental refresh, resume, deletion detection, and attachments. See the Backups guide.

Command	Description	Key flags
backup	Full account backup with incremental refresh, resume, deletion detection, attachment downloads, and optional compression	--out --full --resume --reconcile --keep-history --since --include --exclude --attachments --compress --parallel --dry-run

doctor

diagnostics

Diagnose your environment, auth, and connectivity.

Command	Description	Key flags
doctor	Run diagnostic checks on the CLI environment	—

version

command

Command	Description	Key flags
version	Show CLI version and environment info	—

Global flags

These work on every command.

Flag	Description	Default
--output	Output format (table · json · yaml · csv).	table
--jq	Apply a jq expression to JSON output.	—
--fields	Project a comma-separated subset of fields.	all
--profile	Use a named auth profile.	default
--no-color	Disable ANSI colors.	false
--verbose	Verbose logging to stderr.	false
--no-retry	Disable automatic retry on rate limits.	false
--timeout	Per-request timeout in ms.	—

See Output & filtering for details.

Exit codes

Deterministic, so scripts and agents can branch on the result.

Code	Meaning
0	success
1	Usage / generic error
65	Validation error (HTTP 422)
69	Help Scout API unavailable (5xx)
70	Unexpected internal error
75	Rate limited — retry with backoff
77	Not authenticated / forbidden (401, 403)
78	Configuration error

Full guide: Exit codes.