{"id":35118527,"url":"https://github.com/stephendolan/helpscout-cli","last_synced_at":"2026-06-12T04:01:25.345Z","repository":{"id":328049859,"uuid":"1114080244","full_name":"stephendolan/helpscout-cli","owner":"stephendolan","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-09T21:08:49.000Z","size":214,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T23:07:53.458Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephendolan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T21:49:29.000Z","updated_at":"2026-06-09T21:09:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stephendolan/helpscout-cli","commit_stats":null,"previous_names":["stephendolan/helpscout-cli"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/stephendolan/helpscout-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephendolan%2Fhelpscout-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephendolan%2Fhelpscout-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephendolan%2Fhelpscout-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephendolan%2Fhelpscout-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephendolan","download_url":"https://codeload.github.com/stephendolan/helpscout-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephendolan%2Fhelpscout-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34228097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-27T22:50:56.696Z","updated_at":"2026-06-12T04:01:25.332Z","avatar_url":"https://github.com/stephendolan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Help Scout CLI\n\n[![npm version](https://img.shields.io/npm/v/@stephendolan/helpscout-cli.svg)](https://www.npmjs.com/package/@stephendolan/helpscout-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA CLI for Help Scout's Mailbox API 2.0. JSON output by default for LLM and automation workflows.\n\n## Installation\n\n```bash\nbun install -g @stephendolan/helpscout-cli\n\n# Or run without installing\nbunx @stephendolan/helpscout-cli conversations list\n```\n\n**Linux**: Requires `libsecret` for keychain storage (`apt install libsecret-1-dev`), or use environment variables.\n\n## Authentication\n\nCreate an OAuth app at [Help Scout \u003e Your Profile \u003e My Apps](https://secure.helpscout.net/authentication/authorizeClientApplication).\n\n```bash\nhelpscout auth login --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET\nhelpscout auth status\nhelpscout auth logout\nhelpscout auth refresh                          # Refresh access token\n```\n\nOr use environment variables: `HELPSCOUT_APP_ID`, `HELPSCOUT_APP_SECRET`, `HELPSCOUT_MAILBOX_ID`\n\n## Commands\n\n### Conversations\n\n```bash\nhelpscout conversations list\nhelpscout conversations list --status active --mailbox 123 --tag urgent\nhelpscout conversations list -q 'status:open customer:john@example.com'\nhelpscout conversations list --summary\n\nhelpscout conversations view 456\nhelpscout conversations threads 456\nhelpscout conversations threads 456 --type customer  # Filter by type\nhelpscout conversations threads 456 --html          # HTML output\nhelpscout conversations threads 456 --include-notes\nhelpscout conversations status 456 closed\nhelpscout conversations reply 456 --text \"Thanks for reaching out!\"\nhelpscout conversations note 456 --text \"Internal note\"\nhelpscout conversations add-tag 456 urgent\nhelpscout conversations remove-tag 456 urgent\nhelpscout conversations delete 456\n```\n\n### Customers\n\n```bash\nhelpscout customers list\nhelpscout customers list --first-name John\nhelpscout customers view 789\nhelpscout customers create --first-name John --last-name Doe --email john@example.com\nhelpscout customers update 789 --organization \"Acme Corp\"\nhelpscout customers delete 789\n```\n\n### Users\n\n```bash\nhelpscout users list\nhelpscout users list --email user@example.com\nhelpscout users list --mailbox 123 --page 2\nhelpscout users view 456\n```\n\nUser responses include the `mention` handle when Help Scout returns one. Use `@mention` in Help Scout thread bodies to mention teammates.\n\n### Tags, Workflows, Mailboxes\n\n```bash\nhelpscout tags list\nhelpscout tags view 123\n\nhelpscout workflows list\nhelpscout workflows list --type manual\nhelpscout workflows run 123 --conversations 456,789\nhelpscout workflows activate 123\nhelpscout workflows deactivate 123\n\nhelpscout mailboxes list\nhelpscout mailboxes view 123\nhelpscout mailboxes set-default 123\nhelpscout mailboxes get-default\nhelpscout mailboxes clear-default\n```\n\n### MCP Server\n\nRun as an MCP server for AI agent integration:\n\n```bash\nhelpscout mcp\n```\n\nThe MCP server exposes:\n\n- Typed tools for Help Scout search, full conversation detail, full conversation thread history, mailbox/customer/user lookup, and safe draft-note/status mutations\n- `get_conversation` accepts internal conversation IDs or visible ticket numbers like `#12345`\n- `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\n- `update_conversation_status` safely changes ticket status, with `open` normalized to Help Scout's `active` status\n- `create_note` adds private notes and can optionally set the ticket status, such as closing no-action tickets\n- User lookup tools expose Help Scout mention handles for composing `@mention` references\n- Resource templates for `helpscout://conversation/{conversationId}`, `helpscout://customer/{customerId}`, and `helpscout://user/{userId}`\n- Prompt templates for `summarize_ticket` and `draft_reply`\n\nRead-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.\n\n## Options\n\n| Flag | Description |\n|------|-------------|\n| `-c, --compact` | Minified JSON output |\n| `-p, --plain` | Strip HTML from body fields |\n| `-f, --fields \u003cfields\u003e` | Include only specified fields |\n| `--include-metadata` | Include `_links` and `_embedded` |\n\n## Examples\n\n```bash\nhelpscout conversations list | jq '.conversations[].subject'\nhelpscout conversations list --fields id,subject\n```\n\nErrors: `{\"error\": {\"name\": \"...\", \"detail\": \"...\", \"statusCode\": 400}}`\n\n## References\n\n- [Help Scout API Docs](https://developer.helpscout.com/mailbox-api/)\n- [Search Filters](https://docs.helpscout.com/article/47-search-filters-with-operators)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephendolan%2Fhelpscout-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephendolan%2Fhelpscout-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephendolan%2Fhelpscout-cli/lists"}