Docs (knowledge base)

The docs group talks to the Help Scout Docs API, a separate product with its own per-user API key, independent of your Mailbox/Inbox login.

Authenticate

Find your Docs API key in the web app under your profile → Authentication → API Keys (you need the “Docs: Create new, edit settings & Collections” permission), then store it once in your OS keychain:

zsh — hscli

$ hscli docs auth
✓ Docs API key stored for profile "default"

For CI, pass it through the environment instead — no keychain needed:

HSCLI_DOCS_API_KEY="$HELPSCOUT_DOCS_KEY" hscli docs site list

Sites & collections

hscli docs site list
hscli docs site get <siteId>
hscli docs collection list --site <siteId> --visibility public
hscli docs collection get <id>
hscli docs category list <collectionId>

Articles

# list articles in a collection (or a category)
hscli docs article list --collection <id> --status published

# fetch one article — the body HTML lives in the `text` field
hscli docs article get <id> --output json --jq '.[].text'

# full-text search across the knowledge base
hscli docs article search "password reset" --collection <id>

Create, update & delete articles

hscli docs article create --collection <id> --name "Title" --text @article.html --status notpublished
hscli docs article update <id> --status published
hscli docs article delete <id> --yes

New articles default to notpublished, so nothing goes public by accident. --text takes inline HTML or @file, and delete prompts for confirmation unless you pass --yes.

Drafts

Stage changes without touching the published article — useful for reviewing before going live:

hscli docs article save-draft <id> --text @draft.html   # stage a draft
hscli docs article delete-draft <id> --yes              # discard it; published text is kept

Manage collections & categories

hscli docs collection create --site <siteId> --name "Guides" --visibility public
hscli docs collection update <id> --name "Renamed"
hscli docs collection delete <id> --yes

hscli docs category create --collection <id> --name "Billing"
hscli docs category update <id> --name "Renamed" --order 2
hscli docs category delete <id> --yes

The Docs API requires --name on every collection/category update, even when you only mean to change --visibility or --order. Deletes prompt for confirmation unless you pass --yes.

Caution

Deleting a collection removes every article inside it. There is no undo.

Note

The Docs API is rate-limited per 10-minute window; large pulls back off automatically on 429.

See the command reference for every command and flag.