Authentication

hscli authenticates with Help Scout over OAuth 2.0 and stores your tokens in the operating-system keychain — never in plaintext on disk. One hscli auth login and every command is ready to run.

Logging in

Run the interactive login. hscli opens your browser, completes the OAuth flow, and writes the resulting token to your keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux).

zsh — hscli

$ hscli auth login
# → opens https://secure.helpscout.net/authentication/oauth ...
✓ Authenticated as jordan@acme.io (Acme Support)
✓ Token stored in keychain

Bringing your own Help Scout OAuth app? Run hscli auth setup once (or set HSCLI_APP_ID and HSCLI_APP_SECRET) to register its credentials.

Non-interactive auth (CI & servers)

For headless environments, use the client-credentials grant with your app's credentials. hscli reads them from the environment and authenticates with no browser:

ci.sh

export HSCLI_APP_ID="$HELPSCOUT_APP_ID"
export HSCLI_APP_SECRET="$HELPSCOUT_APP_SECRET"
hscli auth login --client-credentials
hscli conv list --status active --output json

Environment variables

Variable	Description	Default
HSCLI_APP_ID	OAuth app client ID (for --client-credentials / setup).	—
HSCLI_APP_SECRET	OAuth app client secret.	—
HSCLI_DOCS_API_KEY	Help Scout Docs API key (separate product — see below).	—
HSCLI_PROFILE	Named profile to use for multi-account setups.	default
NO_COLOR	Disable ANSI colors (standard convention).	—

Never commit your secrets

Store HSCLI_APP_SECRET as a masked secret in your CI provider. hscli redacts credentials from its own logs and error output.

Multiple accounts

Manage several Help Scout accounts with named profiles. Each profile keeps its own keychain entry; switch with --profile or the HSCLI_PROFILE variable.

zsh — hscli

$ hscli auth login --profile staging
$ hscli conv list --profile staging
$ hscli auth status
default   jordan@acme.io     ✓ valid
staging   bot@acme-test.io   ✓ valid

Docs API key (separate product)

Help Scout Docs (the knowledge base) is a different product from the Mailbox/Inbox, and it authenticates with its own per-user API key — not your OAuth login. The hscli docs * commands use that key exclusively; everything else uses OAuth.

Store it once in your keychain, or pass it through the environment for CI:

zsh — hscli

$ hscli docs auth                         # prompts for the key, validates, stores it
✓ Docs API key stored for profile "default"

# CI — no keychain needed
HSCLI_DOCS_API_KEY="$HELPSCOUT_DOCS_KEY" hscli docs site list

Find the key in the Docs web app under your profile → Authentication → API Keys (you need the "Docs: Create new, edit settings & Collections" permission). The key is stored per profile, so multi-account setups keep their Docs keys separate too. See the Docs guide for the full command surface.

Using with agents

Because hscli is fully self-describing, an AI agent can discover the entire surface from hscli --help and operate it safely. Three properties make this reliable:

• Deterministic exit codes — 0 success, 77 not authenticated, 75 rate-limited, and so on. The agent always knows what happened.
• Structured output — --output json gives the agent machine-readable data with no scraping.
• A locked escape hatch — hscli api reaches any endpoint, but only on the Help Scout host, so a hallucinated URL can't exfiltrate the token.

Tip for Claude Code & Codex

Add hscli --help to your agent's context, or drop this docs URL into the prompt. No SDK or wrapper code required. See Using with agents.