← 返回手册首页
CLI 命令参考 v2.15.0
§ 1 Overview
自 v2.7 起，agent-center CLI 精简为部署 / 生命周期 / 运维专用，约 25 条命令。所有数据管理与查询功能（任务、议题、对话、Agent 管理、Observability 等）已迁移至 Web Console API（/api/* JSON endpoint + SSE）。
CLI 保留的职责：
- 启动 center / worker 常驻进程
- 数据库 migration
- 安装、升级、卸载部署单元
- Worker 注册与状态查询
- Admin token 管理、备份、blob 迁移
- 本机多实例与测试沙箱管理
全局 flag：
| Flag | 说明 |
|---|
--config=<path> / -c | 指定配置文件路径；默认 /etc/agent-center/config.yaml；也可通过 AGENT_CENTER_CONFIG 环境变量设置 |
--format=table|json|text | 输出格式（查询类命令）；默认 table |
§ 2 Server 命令
agent-center server
| 语法 | agent-center server [--config=<path>] |
| 说明 | 启动 center 常驻进程。启动时自动执行 migrate.Up，按顺序完成：解析 config → 打开 SQLite → 跑 migration → 初始化 BlobStore → 启动 admin endpoint（unix socket + 可选 TCP TLS）→ 启动 Web Console HTTP（:7100，loopback only）→ 启动 outbox relay + 定时器 → ready。任何步骤失败立即 panic 退出（fail-fast）。 |
| 关键 flag | --config=<path> — 配置文件路径 |
agent-center migrate
| 语法 | agent-center migrate <subcommand> |
| 说明 | Migration 命令组。 |
agent-center migrate up
| 语法 | agent-center migrate up [--config=<path>] |
| 说明 | 手动执行数据库 migration（fail-fast 调试用）。通常不需要手动执行，因为 server 启动时会自动跑。 |
agent-center migrate v1-to-v2
| 语法 | agent-center migrate v1-to-v2 [--config=<path>] |
| 说明 | v1 → v2 数据迁移工具。仅在从 v1 升级到 v2 时使用一次。 |
§ 3 Install / Uninstall / Upgrade
agent-center install center
| 语法 | agent-center install center [--instance=<name>] |
| 说明 | 安装 center 部署单元：创建系统用户 / 目录 / systemd（Linux）或 launchd（macOS）service unit，symlink binary 到 /usr/local/bin/agent-center。若已安装则自动走升级路径。 |
| 关键 flag | --instance=<name> — 支持单机多实例部署（v2.7.1 #211），不同 instance 使用不同 install prefix + service label |
agent-center install worker
| 语法 | agent-center install worker [--config=<path>] |
| 说明 | 安装 worker daemon 部署单元（systemd / launchd service unit）。 |
agent-center install test-instance
| 语法 | agent-center install test-instance [flags] |
| 说明 | 创建隔离测试沙箱（1 center + N workers）。沙箱文件落在 ~/.agent-center-test/ 下。（v2.8 #255） |
agent-center uninstall center
| 语法 | agent-center uninstall center [--instance=<name>] |
| 说明 | 卸载 center（移除 service unit + symlink + 数据目录）。是 install center 的逆操作。（v2.5.1） |
agent-center uninstall worker
| 语法 | agent-center uninstall worker |
| 说明 | 卸载 worker daemon。是 install worker 的逆操作。 |
agent-center uninstall test-instance
| 语法 | agent-center uninstall test-instance [flags] |
| 说明 | 拆除测试沙箱。是 install test-instance 的逆操作。（v2.8 #255） |
agent-center upgrade center
| 语法 | agent-center upgrade center [--instance=<name>] |
| 说明 | 升级 center binary（swap binary + 重启 service）。要求已有安装，否则拒绝并提示先 install。（v2.5.2） |
agent-center upgrade worker
| 语法 | agent-center upgrade worker |
| 说明 | 升级 worker binary。要求已有安装。 |
§ 4 Worker 命令
agent-center worker enroll
| 语法 | agent-center worker enroll <bootstrap-token> [--config=<path>] |
| 说明 | Worker 首次注册到 center。使用 bootstrap token 兑换 session token，完成 Worker 入库 + capabilities 探测上报。Session token 落盘到 ~/.agent-center/credentials（mode 0600）。 |
agent-center worker list
| 语法 | agent-center worker list [--format=table|json|text] |
| 说明 | 列出所有已注册 worker 及其状态（online / offline）。 |
agent-center worker status
| 语法 | agent-center worker status <worker_id> [--format=table|json|text] |
| 说明 | 查看单个 worker 的详细信息：状态、capabilities、concurrency 配置、最后心跳时间等。 |
agent-center worker run
| 语法 | agent-center worker run [--config=<path>] |
| 说明 | 启动 worker daemon 常驻进程。通常由 systemd / launchd 管理，不需要手动执行。 |
agent-center worker shim
| 语法 | agent-center worker shim <execution_id> |
| 说明 | Per-execution shim 进程。系统内部命令（audience: Sys），由 worker daemon 自动 spawn，用户不直接调用。 |
agent-center worker mcp-host
| 语法 | agent-center worker mcp-host |
| 说明 | Per-agent stdio MCP server。系统内部命令（audience: Sys），由 daemon 内部 spawn，为每个 agent 提供 MCP 工具注入通道。（v2.7 b3-i） |
agent-center worker agent-supervisor
| 语法 | agent-center worker agent-supervisor |
| 说明 | 持久化 per-agent supervisor 进程。系统内部命令（audience: Sys），由 daemon 内部 spawn。（v2.7 D2-f s1） |
§ 5 Admin 命令
agent-center admin backup
| 语法 | agent-center admin backup [--config=<path>] |
| 说明 | 执行 SQLite 数据库备份。 |
agent-center admin blob-migrate
| 语法 | agent-center admin blob-migrate [--config=<path>] |
| 说明 | BlobStore 后端切换数据迁移（例如从本地文件系统迁移到 S3）。 |
agent-center admin token create
| 语法 | agent-center admin token create [--scope=<scope>] [--ttl=<duration>] |
| 说明 | 创建 admin bearer token。明文 token 仅在创建时返回一次。（v2.3-3a） |
agent-center admin token list
| 语法 | agent-center admin token list [--format=table|json|text] |
| 说明 | 列出所有 admin bearer token（不含明文值）。 |
agent-center admin token revoke
| 语法 | agent-center admin token revoke <token_id> |
| 说明 | 撤销指定 admin token，使其立即失效。 |
§ 6 Utility 命令
agent-center version
| 语法 | agent-center version |
| 说明 | 打印版本号、git commit hash、build time。 |
agent-center bootstrap
| 语法 | agent-center bootstrap [check-systemd] |
| 说明 | 首次安装检查（Phase 7）。验证系统环境是否满足部署前置条件。check-systemd 子命令专门检查 systemd 配置。 |
agent-center list-local-centers
| 语法 | agent-center list-local-centers |
| 说明 | 列出本机所有 center 部署实例。支持多实例场景。（v2.7.1 #211） |
agent-center list-local-workers
| 语法 | agent-center list-local-workers |
| 说明 | 列出本机所有 worker 部署（prod + test）。（v2.8 #170） |
agent-center list-test-instances
| 语法 | agent-center list-test-instances |
| 说明 | 列出 ~/.agent-center-test/ 下的测试沙箱。（v2.8 #255） |
agent-center help
| 语法 | agent-center help [<command>] |
| 说明 | 显示帮助信息。可指定具体命令名查看该命令的详细用法。 |
附录：Exit Code 约定
| Code | 含义 |
|---|
0 | 成功 |
1 | 业务失败（通用） |
2 | Usage 错误（参数缺失 / unknown flag / enum 非法值） |
16 | 版本冲突（乐观锁 CAS 失败） |
17 | 资源 not found |
18 | 状态机非法跃迁 |
19 | Invariant 违反 |
64 | 内部错误（panic / unknown） |
130 | 用户主动 cancel（SIGINT） |
附录：输出格式
所有查询类命令支持 --format flag：
table（默认）— 表格 / 对齐；操作型命令为单行成功信息json — 机器解析；snake_case key；加字段向后兼容，删/改字段视为 breaking changetext — 一行一个 ID（脚本友好，可直接 xargs）
stdout 输出业务数据，stderr 输出日志 / 进度 / debug 信息。--format=json 时 stdout 保证为合法 JSON。