https://github.com/stephendolan/helpscout-cli
https://github.com/stephendolan/helpscout-cli
Last synced: 6 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/stephendolan/helpscout-cli
- Owner: stephendolan
- Created: 2025-12-10T21:49:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-06-09T21:08:49.000Z (9 days ago)
- Last Synced: 2026-06-09T23:07:53.458Z (8 days ago)
- Language: TypeScript
- Size: 209 KB
- Stars: 0
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Help Scout CLI
[](https://www.npmjs.com/package/@stephendolan/helpscout-cli)
[](https://opensource.org/licenses/MIT)
A CLI for Help Scout's Mailbox API 2.0. JSON output by default for LLM and automation workflows.
## Installation
```bash
bun install -g @stephendolan/helpscout-cli
# Or run without installing
bunx @stephendolan/helpscout-cli conversations list
```
**Linux**: Requires `libsecret` for keychain storage (`apt install libsecret-1-dev`), or use environment variables.
## Authentication
Create an OAuth app at [Help Scout > Your Profile > My Apps](https://secure.helpscout.net/authentication/authorizeClientApplication).
```bash
helpscout auth login --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
helpscout auth status
helpscout auth logout
helpscout auth refresh # Refresh access token
```
Or use environment variables: `HELPSCOUT_APP_ID`, `HELPSCOUT_APP_SECRET`, `HELPSCOUT_MAILBOX_ID`
## Commands
### Conversations
```bash
helpscout conversations list
helpscout conversations list --status active --mailbox 123 --tag urgent
helpscout conversations list -q 'status:open customer:john@example.com'
helpscout conversations list --summary
helpscout conversations view 456
helpscout conversations threads 456
helpscout conversations threads 456 --type customer # Filter by type
helpscout conversations threads 456 --html # HTML output
helpscout conversations threads 456 --include-notes
helpscout conversations status 456 closed
helpscout conversations reply 456 --text "Thanks for reaching out!"
helpscout conversations note 456 --text "Internal note"
helpscout conversations add-tag 456 urgent
helpscout conversations remove-tag 456 urgent
helpscout conversations delete 456
```
### Customers
```bash
helpscout customers list
helpscout customers list --first-name John
helpscout customers view 789
helpscout customers create --first-name John --last-name Doe --email john@example.com
helpscout customers update 789 --organization "Acme Corp"
helpscout customers delete 789
```
### Users
```bash
helpscout users list
helpscout users list --email user@example.com
helpscout users list --mailbox 123 --page 2
helpscout users view 456
```
User responses include the `mention` handle when Help Scout returns one. Use `@mention` in Help Scout thread bodies to mention teammates.
### Tags, Workflows, Mailboxes
```bash
helpscout tags list
helpscout tags view 123
helpscout workflows list
helpscout workflows list --type manual
helpscout workflows run 123 --conversations 456,789
helpscout workflows activate 123
helpscout workflows deactivate 123
helpscout mailboxes list
helpscout mailboxes view 123
helpscout mailboxes set-default 123
helpscout mailboxes get-default
helpscout mailboxes clear-default
```
### MCP Server
Run as an MCP server for AI agent integration:
```bash
helpscout mcp
```
The MCP server exposes:
- Typed tools for Help Scout search, full conversation detail, full conversation thread history, mailbox/customer/user lookup, and safe draft-note/status mutations
- `get_conversation` accepts internal conversation IDs or visible ticket numbers like `#12345`
- `get_conversation_threads` returns all Help Scout thread types by default, including notes, workflow events, status events, and other system events returned by Help Scout
- `update_conversation_status` safely changes ticket status, with `open` normalized to Help Scout's `active` status
- `create_note` adds private notes and can optionally set the ticket status, such as closing no-action tickets
- User lookup tools expose Help Scout mention handles for composing `@mention` references
- Resource templates for `helpscout://conversation/{conversationId}`, `helpscout://customer/{customerId}`, and `helpscout://user/{userId}`
- Prompt templates for `summarize_ticket` and `draft_reply`
Read-only tools include MCP annotations so hosts can distinguish them from mutating tools, and core read/query tools return structured outputs alongside readable JSON text.
## Options
| Flag | Description |
|------|-------------|
| `-c, --compact` | Minified JSON output |
| `-p, --plain` | Strip HTML from body fields |
| `-f, --fields ` | Include only specified fields |
| `--include-metadata` | Include `_links` and `_embedded` |
## Examples
```bash
helpscout conversations list | jq '.conversations[].subject'
helpscout conversations list --fields id,subject
```
Errors: `{"error": {"name": "...", "detail": "...", "statusCode": 400}}`
## References
- [Help Scout API Docs](https://developer.helpscout.com/mailbox-api/)
- [Search Filters](https://docs.helpscout.com/article/47-search-filters-with-operators)
## License
MIT