Exit codes

hscli returns deterministic, sysexits-style exit codes. Scripts and agents can branch on the result without parsing output.

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 or forbidden (401 / 403)
78	Configuration error

Branching on the result

handle the common cases

hscli conv list --status active --output json
case $? in
  0)  echo "ok" ;;
  77) echo "re-authenticate: hscli auth login" ; exit 77 ;;
  75) echo "rate limited — backing off" ; sleep 30 ;;
  69) echo "Help Scout unavailable — retry later" ; exit 69 ;;
  *)  echo "unexpected error" ; exit 1 ;;
esac

Tip

With --output json, errors are also written to stderr as a JSON object ({ "error", "message", "exitCode" }) — so an agent can read the reason as well as the code. Add --verbose to include the API request path and response body.