hs

使用 hs 从终端与 HelpScout 交互。两个 API 命名空间：hs inbox（Mailbox API — 对话、客户、用户、团队等）和 hs docs（Docs API — 站点、集合、分类、文章）。

认证

Inbox 使用 OAuth2 客户端凭证（App ID + App Secret）。Docs 使用 API 密钥。

• - hs inbox auth login — 交互式设置，对 API 进行验证
• hs docs auth login — 提示输入 Docs API 密钥，进行验证
• hs inbox auth status / hs docs auth status — 检查存储的凭证
• hs inbox auth logout / hs docs auth logout — 移除凭证

凭证解析顺序：OS 密钥环 → 配置文件。对于非交互式认证，使用 hs inbox config set --inbox-app-id --inbox-app-secret 。

Inbox 命令

对话（conv）

• - hs inbox conv list --status active --mailbox --tag --assigned-to --embed threads
• hs inbox conv get --embed threads
• hs inbox conv create --mailbox --subject ... --customer --body ...
• hs inbox conv update --status closed --subject ...
• hs inbox conv delete
• hs inbox conv threads list
• hs inbox conv threads reply --customer --body ... --status closed
• hs inbox conv threads note --body ...
• hs inbox conv tags set --tag billing --tag urgent
• hs inbox conv fields set --field =
• hs inbox conv attachments upload --thread-id --file ./path

客户（cust）

• - hs inbox cust list --query email:jane@example.com
• hs inbox cust get
• hs inbox cust create --first-name Jane --last-name Doe --email jane@example.com
• hs inbox cust update --last-name Smith
• hs inbox cust delete

邮箱（mb）

• - hs inbox mb list / hs inbox mb get
• hs inbox mb folders list / hs inbox mb custom-fields list

用户

• - hs inbox users list --email user@co.com / hs inbox users get / hs inbox users me
• hs inbox users status get / hs inbox users status set --status away

团队

• - hs inbox teams list / hs inbox teams members

组织

• - hs inbox organizations list --query acme / hs inbox organizations get
• hs inbox organizations create --name Acme Corp / hs inbox organizations delete

标签 / 评分

• - hs inbox tags list / hs inbox ratings list

工作流（wf）

• - hs inbox wf list / hs inbox wf run --conversation-ids id1,id2
• hs inbox wf update-status --status active

Webhooks（wh）

• - hs inbox wh list / hs inbox wh get
• hs inbox wh create --url https://... --events convo.created --secret s3cret
• hs inbox wh delete

已保存回复

• - hs inbox saved-replies list --mailbox-id
• hs inbox saved-replies create --mailbox-id --name Greeting --body Hello...

报告

• - hs inbox reports conversations --start 2025-01-01 --end 2025-01-31 --mailbox
• 子命令：chats、company、conversations、customers、docs、email、productivity、ratings、users

工具

• - hs inbox tools briefing — 每日简报摘要
• hs inbox tools briefing --assigned-to --embed threads — 特定代理的简报，包含线程内容

Docs 命令

站点

• - hs docs sites list / hs docs sites get
• hs docs sites create --subdomain help --title Help Center

集合

• - hs docs collections list --site / hs docs collections get
• hs docs collections create --site --name Getting Started

分类

• - hs docs categories list / hs docs categories get
• hs docs categories create --collection --name FAQ
• hs docs categories reorder --categories id1,id2,id3

文章

• - hs docs articles list --collection 或 --category
• hs docs articles search --query password reset --site
• hs docs articles get / hs docs articles get --draft
• hs docs articles create --collection --name How to reset --text Step 1...
• hs docs articles update --text Updated... --status published
• hs docs articles delete
• hs docs articles draft save --text ... / hs docs articles draft delete
• hs docs articles revisions list / hs docs articles revisions get
• hs docs articles upload --file ./image.png

重定向

• - hs docs redirects list / hs docs redirects find --site --url /old-path
• hs docs redirects create --site --url-mapping /old --redirect /new

资源

• - hs docs assets article upload --file ./img.png
• hs docs assets settings upload --file ./logo.png

输出与全局标志

• - --format table|json|json-full|csv — 输出格式（默认：table）
• --no-paginate — 自动获取所有页面
• --page / --per-page — 分页（默认值：1, 25）
• --debug — 显示 HTTP 请求/响应详情

配置

• - hs config set --format json --inbox-default-mailbox 12345
• hs config get [key] — 打印一个或所有配置值
• hs config path — 打印配置文件位置
• 默认位置：~/.config/hs/config.yaml（Linux/macOS），%AppData%\hs\config.yaml（Windows）

PII 脱敏

Inbox 命令使用确定性假身份对客户/用户的 PII 进行脱敏。通过配置键 inboxpiimode 控制。

• - hs inbox 上的 --unredacted 标志可在单次调用中禁用脱敏（需要在配置中设置 inboxpiiallow_unredacted: true）

权限

白名单模型 — 限制代理可以运行的命令。空策略 = 无限制。

• - 通过配置键 inboxpermissions / docspermissions 设置 — 逗号分隔的 resource:operation 对
• 通配符：:read、conversations:
• 操作：read、write、delete、*
• hs inbox permissions — 检查当前策略，显示每个命令的 ALLOW/DENY

示例：hs inbox config set --inbox-permissions conversations:read,customers:read,mailboxes:read

备注

• - 自我更新：hs update
• Shell 补全：hs completion bash|zsh|fish|powershell