Skip to content
hscli

Using with agents

hscli is built to be driven by AI agents as easily as by a human. Point an agent at hscli --help and it has a complete, self-describing toolset for conversations, customers, reporting, and backups — no SDK glue required.

Why it works for agents

Section titled “Why it works for agents”
  • Self-describing — hscli --help and hscli <group> --help enumerate every command and flag, so the agent can discover the surface at runtime.
  • Structured output — --output json returns machine-readable data with no scraping.
  • Deterministic exit codes — the agent always knows whether a step succeeded (0), needs re-auth (77), or was rate-limited (75).
  • A locked escape hatch — hscli api can reach any endpoint, but only on the Help Scout host, so a hallucinated URL can't exfiltrate the token.

Give the agent context

Section titled “Give the agent context”

The simplest setup is to let the agent read the help text, or drop this docs URL into the prompt:

claude code
hscli --help            # full command tree
hscli conv --help       # one group in detail

A real loop

Section titled “A real loop”

Ask the model what to do, then act on its answer with real commands:

triage the active queue
hscli conv list --status active --output json --fields id,subject \
  | claude -p 'return JSON: [{"id":<id>,"tag":<tag>}] for each conversation' \
  | jq -r '.[] | "\(.id) \(.tag)"' \
  | xargs -n2 sh -c 'hscli conv tag "$0" --add "$1"'