内容
# wootctl
> 🏭 [cliwright](https://cliwright.jjuanrivvera.com) 命令行工具集的一部分。
一款快速、可脚本化的命令行工具，支持完整的 [Chatwoot](https://www.chatwoot.com) API。
`wootctl` 封装了 Chatwoot 文档中所有操作 —— 涵盖应用、平台和公共客户端 API 的 144 个操作 —— 并提供命名配置文件以跨多个实例工作、操作系统密钥环令牌存储（带有针对无头主机的加密文件备用方案）、表/json/yaml/csv 输出，以及一个 MCP 服务器，以便 AI 代理可以安全地驱动它。
```console
$ wootctl conversations list --status open
ID INBOX_ID STATUS PRIORITY
42 3 open high
57 1 open
$ wootctl messages create 42 --content "On it — checking now."
$ wootctl conversations toggle-status 42 --status resolved
```
## 安装
```bash
# 安装脚本（macOS / Linux）—— 下载发布二进制文件，验证其校验和
curl -fsSL https://raw.githubusercontent.com/jjuanrivvera/wootctl/main/install.sh | sh
# Homebrew（macOS / Linux）
brew install jjuanrivvera/wootctl/wootctl-cli
# Scoop（Windows）
scoop bucket add wootctl https://github.com/jjuanrivvera/scoop-wootctl
scoop install wootctl
# Go
go install github.com/jjuanrivvera/wootctl/cmd/wootctl@latest
```
deb/rpm/apk 软件包和预编译存档可在 [发布页面](https://github.com/jjuanrivvera/wootctl/releases) 找到。发布版本均经过 cosign 签名，并附带 SBOM。
## 设置
```bash
wootctl auth login
```
系统将提示您输入实例 URL 和 `api_access_token`（Chatwoot → 个人资料设置 → 访问令牌；输入将被隐藏）。令牌将被实时验证，账户将被选中，所有内容都将被保存：令牌存储在您的操作系统密钥环中，其他内容存储在 `~/.wootctl-cli/config.yaml` 中。
无密钥环的无头主机？设置 `WOOTCTL_KEYRING_PASSWORD`，令牌将转而存储在 AES-256-GCM 加密文件中。CI 环境？`WOOTCTL_API_KEY` 可覆盖所有内容。
### 配置文件
通过保存每个实例（或账户）为一个配置文件，可以跨多个 Chatwoot 实例（或账户）工作：
```bash
wootctl --profile staging auth login # 保存第二个实例
wootctl config list-profiles # 查看它们
wootctl config use staging # 切换默认配置
wootctl --profile staging convs list # 一次性覆盖
```
配置文件捆绑了基本 URL + 账户 ID + 令牌，因此切换配置文件会一次性切换所有内容。`WOOTCTL_PROFILE` 可为每个 shell 选择一个配置文件。
## 命令
| 分组 | 命令 |
|---|---|
| 会话 | `list · meta · create · get · update · filter · labels · add-labels · assign · toggle-status · toggle-priority · toggle-typing · set-custom-attributes · reporting-events` |
| 消息 | `list · create (with --attachment multipart) · delete` |
| 联系人 | `list · create · get · update · delete · search · filter · merge · conversations · contactable-inboxes · create-contact-inbox · labels · add-labels` |
| 收件箱 | `list · create · get · update · agent-bot · set-agent-bot · members · add/update/remove-members` |
| 团队 | `list · create · get · update · delete · members · add/update/remove-members` |
| 报告 | `overview · summary · account/agent-conversations · first-response-time-distribution · inbox-label-matrix · outgoing-messages-count · agent/channel/inbox/team-summary · events` |
| 其它 | `account · agents · agent-bots · audit-logs · automation-rules · canned-responses · custom-attributes · custom-filters · integrations · labels · portals · profile · webhooks · csat` |
| `platform …` | accounts, account-users, agent-bots, users (+ sso-link) — platform app token |
| `client …` | the public, unauthenticated contact-facing API (inbox, contacts, conversations, messages) |
任何未封装的操作（目前没有）都可以通过逃生门实现：
```bash
wootctl api GET api/v2/accounts/1/reports/summary -q since=1780272000
```
完整的命令参考文档位于 [docs/commands](docs/commands/wootctl.md)。
## 输出和脚本
```bash
wootctl contacts search --q ana -o json | jq '.[0].email'
wootctl labels list -o id | xargs -n1 wootctl labels get
wootctl conversations list --all --filter status=open -o csv > open.csv
wootctl agents list --columns name,email
wootctl conversations list --jq '.[3].meta.sender.name'
```
`table`（默认，TTY 颜色，`NO_COLOR` 优先级高），`json`，`yaml`，`csv`（公式注入净化），和 `id`（每行一个，管道友好）。`--all` 会遍历每一页。`--dry-run` 会打印确切的 curl（令牌被遮蔽）而不是调用：
```console
$ wootctl labels create --title vip --dry-run
curl -X POST 'https://…/api/v1/accounts/1/labels' -H 'api_access_token: REDACTED' \
-H 'Content-Type: application/json' -d '{"title":"vip"}'
```
## AI 代理
`wootctl` 在两个方向上都支持 AI 代理：
```bash
wootctl mcp claude enable # 暴露 125 个注释的 MCP 工具（读取/写入/破坏性）
wootctl agent guard --host claude-code --write # 为使用 Bash 的代理安装防护措施
```
MCP 接口排除了身份验证/配置/配置文件切换和所有机密标志。防护措施硬阻止不可逆操作（删除、`contacts merge`）—— 包括所有 cobra 别名路径和原始 `api` 出口，用于写入方法 —— 通过 PreToolUse 钩子，该钩子在引用技巧和路径前缀二进制文件时仍然存在。`codex` 和 `opencode` 目标被包含在内。
## 备份、恢复和同步（超出 API）
除了原始端点之外，wootctl 将您的账户 **配置** 视为可以版本化和在实例之间移动的内容 —— 标签、预设响应、自定义属性、自定义过滤器、自动化规则、团队、Web 钩子和代理机器人（永不包括会话/联系人/消息，它们是实时数据）。
```bash
# 将配置转储到 git 友好目录（每个种类一个 YAML 文件，仅可写入字段）
wootctl backup --dir ./chatwoot-config
git -C ./chatwoot-config add -A && git -C ./chatwoot-config commit -m "chatwoot config"
# 将备份重新同步到账户：创建缺失的，更新更改的，跳过未更改的
wootctl restore --dir ./chatwoot-config --dry-run # 始终先预览
wootctl restore --dir ./chatwoot-config
wootctl restore --dir ./chatwoot-config --only labels --prune # 还可以删除漂移
# 多实例收益，官方 CLI 无法实现：跨实例推广配置
wootctl sync --to production --dry-run
wootctl sync --to production --only canned-responses,labels
wootctl --profile staging sync --to production --prune
```
匹配基于自然键（标题、短代码、名称、URL、属性键）；"未更改"仅比较可写入字段，因此 `id`/时间戳永远不会导致幻影更新。在一个账户中出现两次的键被跳过，永远不会被修剪 —— wootctl 不会对模糊匹配执行操作。`restore` 和 `sync` 被归类为破坏性，因此 `wootctl agent guard` 硬阻止 AI 代理执行它们。
## 与官方 `chatwoot` CLI 的比较
官方 [Chatwoot CLI](https://developers.chatwoot.com/cli) 在其涵盖的范围内表现良好，如果您只需要驱动一个实例的会话，它可能就是您所需要的。`wootctl` 的存在是因为我们需要更多功能：
- **覆盖范围**：wootctl 封装了所有 144 个已文档化的操作（应用程序 + 平台 + 公共客户端 API），由 CI 中的规范完整性门控强制执行。官方 CLI 涵盖了核心会话工作流程。
- **多配置文件**：跨实例/账户的命名配置文件。
- **无头主机**：当没有 OS 密钥环时，备用加密文件密钥环。
- **代理接口**：具有安全注释的 MCP 服务器 + 生成的防护措施。
- **超出 API**：`backup`/`restore` 账户配置和跨实例 `sync` —— 在实例之间推广标签/预设响应/自动化。
- **脚本**：json/yaml/csv/id 输出，`--jq`，`--dry-run` curls，`--all` 分页。
在官方 CLI 真正更好的地方：它是第一方（在同一团队文档化新端点的瞬间跟踪），具有上游支持，其 TUI 样式会话流程对于交互式分诊更加精致。两者可以共存 —— 二进制文件不会冲突。
## 开发
```bash
make build # bin/wootctl
make check # fmt + vet + lint + tests
make verify # 完整的确定性门控（规范检查、完整性、覆盖率、DoD）
```
CLI 接口绑定到 [api-manifest.json](api-manifest.json)，源自 Chatwoot 自己的 OpenAPI 规范；如果它们发散，则 `make spec-check` 会失败，如果清单涵盖的 API 少于枚举的 API，则 `make spec-completeness` 会失败。设计决策记录在 [DECISIONS.md](DECISIONS.md) 中。
## 许可证
MIT
