helpscout-cli

CLI for Help Scout customer support — list/search conversations, reply to tickets, add internal notes, manage customers, and more. All commands return structured JSON for easy piping into other tools.

Setup

1. Create an OAuth2 app in Help Scout: Profile → My Apps → Create My App. Copy the App ID and App Secret.

2. Clone and install:

   git clone https://github.com/gxbvc/helpscout-cli.git ~/tools/helpscout-cli
   cd ~/tools/helpscout-cli
   cp .env.example .env   # then fill in HELPSCOUT_APP_ID and HELPSCOUT_APP_SECRET
   npm install
   npm run build
   npm link

3. Verify it works:

   helpscout-cli mailboxes

Environment

HELPSCOUT_APP_ID=
HELPSCOUT_APP_SECRET=

The CLI uses the OAuth2 client credentials flow — no browser auth required. Tokens are cached in memory per invocation.

Commands

Mailboxes

helpscout-cli mailboxes                    # List all mailboxes (id, name, email)

Conversations

# List
helpscout-cli conversations list                                # Active conversations (default)
helpscout-cli conversations list --status all --limit 50        # All statuses
helpscout-cli conversations list --mailbox 12345                # Single mailbox
helpscout-cli conversations list --assigned 67890               # Assigned to user
helpscout-cli conversations list --tag urgent                   # Filter by tag
helpscout-cli conversations list --query "refund"               # Search
helpscout-cli conversations list --query "refund" --status closed

# Read
helpscout-cli conversations get 555                             # Conversation + threads
helpscout-cli conversations get 555 --raw                       # Keep HTML in thread bodies

# Reply
helpscout-cli conversations reply 555 --text "Thanks — looking into it now."
helpscout-cli conversations reply 555 --html "<p>Done, refund issued.</p>" --status closed
helpscout-cli conversations reply 555 --text "Draft reply" --draft

# Internal note
helpscout-cli conversations note 555 --text "Escalating to engineering."

# Workflow
helpscout-cli conversations close 555
helpscout-cli conversations assign 555 --user 67890
helpscout-cli conversations tag 555 --tags "refund,urgent"

# Create a new conversation
helpscout-cli conversations create \
  --mailbox 12345 \
  --customer "jane@example.com" \
  --subject "Following up" \
  --text "Hey Jane, wanted to follow up on your question."

Customers

helpscout-cli customers search "jane@example.com"
helpscout-cli customers search "Jane Doe"

Users (teammates)

helpscout-cli users                        # List all users in the account

Output format

Every command prints one line of JSON: {"ok": true, "data": ...} on success, or {"ok": false, "error": "..."} on failure. Exit code is 0 on success, 1 on error — safe to pipe through jq:

helpscout-cli conversations list --status active --limit 100 | jq '.data[] | {id, subject}'

Notes

• HTML vs text: replies and notes accept either --text (plain, auto-wrapped in <p> tags) or --html (raw). For multi-paragraph replies use --html with explicit <p>...</p> markup.
• Pagination: list commands use --page + --limit (max 50 per page per Help Scout's API).
• Search syntax: --query passes through to Help Scout's search DSL. Combine with --status to AND them together automatically.

License

MIT