CLI 参考

安装与设置#

ClawButler CLI（命令：ap）是通过 pip 或 uv 安装的 Python 工具：

# Install with pip
pip install clawbutler-cli

# Or with uv (recommended)
uv pip install clawbutler-cli

# Or run from repo
cd apps/cli && uv run ap --help

安装后验证：

$ ap --version

clawbutler-cli 0.1.0

身份认证#

使用任何命令前，先向 ClawButler 实例进行身份认证：

使用邮箱/密码或 API 令牌登录。创建存储的配置文件。

$ ap auth login

使用存储的刷新令牌刷新过期的访问令牌。

$ ap auth refresh

清除一个或所有配置文件的存储会话令牌。

$ ap auth logout

显示当前已认证用户的详细信息。

$ ap auth whoami

CLI 支持多个配置文件，方便在不同实例间切换：

显示所有存储的配置文件

$ ap profile list

切换活跃配置文件

$ ap profile use <name>

删除存储的配置文件

$ ap profile remove <name>

命令树#

当前 top-level commands，按大致对应 Web 导航的方式分组。

运营命令

• ap dashboard查看 dashboard summary 与顶层运行态概览
• ap agent列出、查看、启用、禁用、紧急停止和配置代理
• ap approval列出、批准、拒绝、批量处理审批请求并管理规则
• ap kill-switch执行紧急停止与恢复（`trigger` / `recover`）
• ap activity查看实时代理活动流
• ap session列出和检查代理会话
• ap chat与代理进行流式对话

洞察命令

• ap audit搜索和导出审计日志
• ap cost查看成本汇总、趋势和按代理/模型/任务维度的明细
• ap budget管理预算、查看建议、采纳/忽略推荐
• ap cron列出、创建、更新、删除和检查定时任务执行记录
• ap config查看配置版本、对比差异、漂移检测和回滚

效率命令

• ap memory查看和管理代理记忆条目
• ap tool监控工具使用情况、状态和调用历史
• ap report生成、列出、导出和计划报告
• ap template浏览、验证和部署认证模板
• ap runbook列出、触发、检查和管理 Runbook 执行
• ap analytics查看使用分析和性能指标

系统命令

• ap connector管理 connector、discovery import、诊断、同步和 IM 渠道
• ap runtime-host列出已配对 Runtime Host、发现实例、batch-add connector，并同步 attach-mode 会话
• ap org管理组织、成员和角色
• ap notification查看和管理通知偏好设置
• ap health-check运行系统健康检查和诊断
• ap infrastructure查看基础设施状态和服务健康度
• ap supply-chain查看供应链安全和依赖情报

工具命令

• ap auth登录、登出、刷新令牌和检查身份
• ap profile管理存储的连接配置文件
• ap export导出数据（代理、配置、审计日志）为 JSON/CSV
• ap import从文件导入配置
• ap routing查看和管理 A2A 路由规则
• ap capabilities发现代理能力和协议支持

通用选项#

以下标志在大多数命令中可用：

• ---json — 以 JSON 格式输出（代替格式化表格）
• ---page — 页码（默认：1）
• ---page-size — 每页条目数（默认：20，最大：100）
• ---date-from — 开始日期筛选（YYYY-MM-DD）
• ---date-to — 结束日期筛选（YYYY-MM-DD）
• ---profile — 使用指定的存储配置文件
• ---confirm — 危险操作（删除、登出）必需

示例工作流#

日常监控

用规范的 dashboard、agent、approval 命令快速查看运维状态：

$ ap dashboard summary
ap agent list --health-status error
ap approval list --status pending

成本排查

通过 summary、by-agent、trend 三类命令下钻成本变化：

$ ap cost summary --date-from 2026-04-01
ap cost by-agent --date-from 2026-04-01
ap cost trend --granularity week --date-from 2026-04-01

紧急响应

检查单个 Agent，必要时触发 kill switch，再查看 audit 历史：

$ ap agent show <agent-id>
ap kill-switch trigger <agent-id> --reason "Unexpected outbound calls"
ap audit search --agent-id <agent-id> --date-from 2026-04-15

Runtime Host 接入

仅用终端完成已配对主机的发现与 session sync 闭环：

$ ap runtime-host list
ap runtime-host discover <runtime-host-id>
ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>