CLI 参考

herdr-mcp 本机管理与运维命令。

本页只记录 herdr-mcp 自己的命令面。Herdr 本体的 workspace、pane、agent、session CLI 请看官方 Herdr CLI Reference。

herdr-mcp 的命令可以按用途理解，而不是按 bin/ 文件名死记。

日常管理：herdr-mcp#

普通用户应使用 GitHub Release 安装的原生 Rust CLI：

复制herdr-mcp install
herdr-mcp status
herdr-mcp doctor
herdr-mcp update
herdr-mcp update check
herdr-mcp update apply
herdr-mcp update major-apply
herdr-mcp update major-rollback
herdr-mcp update auto
herdr-mcp update status
herdr-mcp worker update
herdr-mcp profile check --file ./workstation-profile.json
herdr-mcp rollback
herdr-mcp reinstall
herdr-mcp uninstall

从 v0.4.3 起，update 是普通用户的一步升级入口，等价于 update apply。已安装的 v0.4.2 binary 仍会把 bare herdr-mcp update 当作只读检查，并把 herdr-mcp update apply 返回为 next_action，因此从 v0.4.2 跨版本升级时应执行一次 herdr-mcp update apply。只有明确需要只读检查版本与 provenance 时才使用 update check。

交互式 update / update apply 会继续把最终机器可读结果写到 stdout，同时把人类可读进度写到 stderr：检查 Release/provenance、验证 artifact attestation、按百分比显示下载进度、校验 candidate、显示 installer 状态，并最终给出经过 health gate 的成功/失败结果。真正的 activation 仍由 detached update worker 执行；前台 CLI 只在有界时间内观察 durable update job，不自行执行 service lifecycle mutation。同 contract 的 Runtime 更新成功提交后，交互式命令还会检查用户自己配置的 Cloudflare Worker；若其 edgeVersion 落后于已验证 Release，Herdr 会临时取得 Cloudflare 授权，只对 health 已证明的同一个 Worker 做原地更新，保留 Worker identity、Durable Objects、secrets、public OAuth origin、已登记设备、Connectors 和已知的可选 artifact R2 binding，并且绝不修改 DNS。如果 Cloudflare 授权或 Worker reconcile 无法完成，Runtime 仍保持已更新状态，结果会明确给出 next_action: herdr-mcp worker update。当 Runtime 已经是目标版本时再次运行 herdr-mcp update，只会补做待完成的 Worker reconcile，不会重装 Runtime。如果安装超过前台观察窗口，命令会返回 update_queued 并带 next_action: herdr-mcp update status；新 Runtime 生效后，update status 会报告 Worker drift。update auto 继续保持非交互、静默后台模式，并且绝不会弹出 Cloudflare 授权；Edge 落后时只报告下一步 herdr-mcp worker update。已经发布且不可变的 v0.4.2 binary 早于这套进度 UI，因此从 v0.4.2 执行一次 update apply 时，网络阶段仍可能暂时没有输出。

herdr-mcp worker update 是已有 fleet 的直接 Edge reconcile 命令。正常用户路径要求默认实例已经 enrollment 且当前 Runtime 为 PROD Release，并使用临时 Cloudflare 授权。fleet 管理 preflight 可以识别精确冻结 hash 的 epoch-2 rollback contract，从而让已经 enrollment 的旧 Worker 原地升级；但 Link/install 数据面的 admission window 仍保持 current/N-1，在 Worker 升级完成前继续 fail-closed。对于精确的 DEV/UAT candidate，只有显式设置 HERDR_MCP_EDGE_BUNDLE_PATH 指向同一个已资格验证 artifact 内的 Edge bundle 时才允许执行。更新仍拒绝 Edge downgrade 或未知 contract hash；遇到未知/自定义 Worker binding 时 fail-closed，不会静默丢配置。它不会创建第二个 Worker、轮换设备/Connector 凭据、改变 OAuth/DNS identity，也不要求删除并重新添加 ChatGPT Connector。

update apply 对不兼容的持久化 state schema 继续 fail-closed。普通 v0.4.8（schema 5）用户升级到 v1.0（schema 15）时，只需要执行一次 herdr-mcp update。不可变的 v0.4.8 updater 会先接纳 schema-5 的 v0.4.9 migration bridge；该 detached bridge 验证最终 schema-15 Runtime 的 attestation，再调用最终 Runtime 自己的 update major-apply，最后原地 reconcile 已经证明身份的 Worker。成功路径不会把 bridge 安装成 production service。

update major-apply 继续作为这条用户路径背后的权威维护者/恢复 primitive。它会先停止正在运行的旧服务，使最终快照包含停机期间已提交的写入，再生成私有、一致的 schema-5 SQLite 备份和一份可执行的旧 runtime binary 私有副本，对两份 rollback artifact 都做哈希校验，最后复用正常的事务式 service install 完成迁移和激活。备份失败时会尝试重新启动旧服务，并报告重启失败；若检测到已存在的 rollback 材料，会在停止服务前直接拒绝，避免重试覆盖此前的备份。update major-rollback 会先校验回滚记录和旧 binary，再停止当前服务，随后校验数据库备份哈希并恢复升级前的数据库并重新安装备份的旧 runtime；私有 binary 副本使回滚不依赖后续 runtime generation GC。回滚接受中断在 5 至 15 之间任意 schema 的迁移，并会清除 v1.0 迁移后新产生的持久化状态。这两个 major lifecycle 命令都会拒绝在 managed herdr_exec 会话内执行。

profile check --file 是只读的设备可移植性 / drift 门禁。Profile JSON 使用 schema_version: 1，强制 secrets_policy: "reauthorize"，可声明项目 {id, remote, path}，以及 can_run_headless、supports_code_edit、supports_shell、supports_vision 等 Agent 能力要求。检查只会对比当前文件系统/Git origin 与已有 Capability Inventory，不安装工具、不复制文件、不携带凭据；未探测的能力保持 drift，不会猜值。报告 inventory 不可用时再执行 herdr-mcp scan --probe。

update auto 是后台调度入口。默认 macOS PROD 实例执行 service install 时会 reconcile 归属明确的 dev.herdr-mcp.auto-update LaunchAgent；任务在加载时先执行一次，随后每天触发。自动安装严格限制为 PROD runtime + Stable Release：编译为 DEV 的 runtime、[update] check = false、named instance、preview 都会在访问网络前直接跳过。发现严格更高的 Stable Release 后，继续复用正常的 provenance 验签、detached worker 和 rollback-safe 更新事务，不新增第二套下载器，也不绕过回滚门槛。service uninstall 会先写入归属明确的持久 update fence 并移除 scheduler；detached worker 在真正 activation 前会再次检查该 fence，因此已经排队的静默更新不能在卸载后复活服务。显式成功的 install 才会解除 fence。

macOS 上，reinstall 是产品级修复 / 重装入口；Linux 的 runtime 修复使用 herdr-mcp install，显式服务移除使用 herdr-mcp service uninstall，下述完整 ownership-checked product-uninstall 事务仍属于 macOS lifecycle 集成。macOS 的 reinstall 会：重新执行 managed Rust service lifecycle，并保留配置与凭据；runtime generations 继续遵循正常 service GC，仅承诺 active / rollback-safe 保留集合。uninstall 会完整清理经过强 ownership 校验的 herdr-mcp runtime/config 状态。默认实例负责自己的 service、归属明确的 auto-update scheduler、Link/watchdog、Native Messaging host、managed user CLI 和 config root；named instance 则严格限定为自己的 service/watchdog/config，不取得默认 scheduler、Link、Native Host 或 user CLI 的 ownership。默认 product uninstall 会在 config 删除后保留一个很小的用户 cache update-fence tombstone，防止此前 detached 的 updater 复活 service；只有显式且成功的 install/reinstall 才清除它。两者都明确不会卸载或修改独立的 herdr executable、Herdr service/socket/config，也不会删除浏览器扩展账号状态、Cloudflare 资源、macOS Keychain 项或 TCC 授权。service uninstall 仍然只是更窄的高级 service primitive。

service ...、link ...、native-host ...、candidate 属于高级/内部命令；dev 是下面单独说明的源码开发入口。正常安装本机 runtime 不需要仓库 checkout、Node.js、npm，也不应把 service install 当作普通用户入口。

快速语义判断#

herdr-mcp semantic 把 Runtime 已有的 provider-neutral 语义层作为正常 CLI 能力开放。语义输出只作辅助判断；task、Git、validation、权限、delivery、cleanup 等确定性事实继续保持原有权威。

复制herdr-mcp semantic status
herdr-mcp semantic setup
herdr-mcp semantic remove <route-name>
herdr-mcp semantic decide --state "..." --question "..." --yes "..." --no "..."
herdr-mcp semantic choose --state "..." --question "..." --option a="..." --option b="..."
herdr-mcp semantic score --state "..." --question "..." --criterion "..." --criterion "..."

setup 不传 route 参数时使用 TypeSafe.ai（decision、jev-latest）作为推荐参考；自定义 route 需要同时提供 --name、--protocol、--url、--model。Provider 身份属于配置数据，不进入硬编码判断分支。API Key 不接受 argv 输入：交互终端使用隐藏输入，自动化可从 stdin 提供一行。对于 typed-decision 协议，setup 会先真实验证当前候选 route，再写入既有 mode-0600 的 config.json；验证失败不会修改原配置。status --json 提供机器可读结果，也不会返回 API Key。

decide、choose、score 复用 Browser Auto、planning、Parent orchestration、Work Memory 正在使用的同一个 Runtime SemanticService route pool。结构化输入使用 --state-json。没有配置 semantic route 时，CLI 会明确说明判断不可用，Herdr 的确定性路径保持不变。

源码开发 Runtime：DEV / PROD#

当前 runtime 只有这一条正式路径可以让开发机 dogfood herdr-mcp 源码，同时始终保留稳定 PROD 恢复源：

复制herdr-mcp dev status
herdr-mcp dev sync --dry-run
herdr-mcp dev sync
herdr-mcp dev rollback

• dev status 只读，显示 runtime channel、active/dev/prod generation、source repo/branch/commit/dirty provenance、runtime/current 是否与记录一致、固定 PROD 快照是否通过校验，以及最近一次真实 dev sync 的 last_transaction。该持久记录包含 transaction ID、phase、目标源码、expected/final generation、终态错误和可用的 activation evidence，因此 runtime 自重启后调用方可以直接确认上一笔结果，而不是重放 sync。
• dev sync --dry-run 只展示计划，不构建、不切换 runtime。
• dev sync 默认要求 clean source checkout，把源码构建成例如 <version>-dev 的 DEV identity；进入 DEV 前先把现有 PROD binary 与 SHA-256 evidence 固定保存在 ~/.config/herdr-mcp/runtime/channels/prod/，并在可能耗时较长的 build 之前把 transaction 写入现有 channel state，再复用正式 transactional service install。只有 server、Native Host、dev.herdr-mcp.link-prod 都 reconcile 到同一个 managed generation，transaction 才记录为 succeeded。
• dev sync --allow-dirty 是给明确的本地实验使用的 provenance override，不应作为日常默认值。
• dev rollback 校验并重新安装固定 PROD binary。连续多次 DEV sync 保留最初固定的 PROD 恢复源，不会把“上一个 DEV generation”当作新的 PROD。

DEV/PROD 切换只影响本机 runtime lifecycle，不部署 Cloudflare Edge，不修改 DNS/OAuth，也不创建第三套长期 test 环境。Runtime DEV/PROD 与扩展 DEV/STANDALONE/STORE 身份模型相互独立。

macOS 权限#

复制herdr-mcp permissions status
herdr-mcp permissions setup
herdr-mcp permissions verify

status 会返回 granted、denied、needs_setup、unknown 或 timeout。setup 会尽可能直接打开完全磁盘访问（Full Disk Access），但不会声称已经替用户授权；macOS 仍要求用户本人确认。verify 通过固定 TCC broker 验证受保护目录。v0.4.3 起，交互式 herdr-mcp install 会在 service 启动前准备 broker，并在仍需授权时打开同一设置页。若 file/git 工具返回 macos_tcc_access_blocked，给 herdr-mcp-broker 开启完全磁盘访问后再执行 verify。

Agent 能力发现：scan#

doctor 回答的是**“这套安装现在健康吗？”。默认输出只保留给人看的摘要：本机健康、Edge 可达性、未执行的远程 Connector 认证，以及真正需要处理的项目。完整分层诊断使用 herdr-mcp doctor --verbose，机器读取使用 herdr-mcp doctor --json。macOS 的 JSON standalone_extension 对象会报告受管 STANDALONE 扩展状态；state=drift 表示 Google Chrome 正在从 ~/.config/herdr-mcp/extensions/standalone/current 之外的路径加载同一个固定 standalone extension ID，对象会给出 expected_path、实际加载路径/profile、Chromium location 和 drift_count。浏览器扩展属于可选能力，因此这条提示不会把原本健康的核心 MCP/service readiness 判成失败。scan 回答的是“这台机器上的 Agent 到底有哪些已经被证据确认的能力？”**。

复制herdr-mcp scan
herdr-mcp scan --json
herdr-mcp scan --probe
herdr-mcp scan --refresh --probe

scan 不会自己重做 Herdr 的 live-agent detection，而是组合当前安装的 Herdr/runtime 已经拥有的三类证据：

• agent.list 是 live Agent 实例、status、pane/workspace、cwd 的权威来源；
• server.agent_manifests 是 Herdr 当前加载 detection manifest 的权威来源；
• 当前安装的 herdr agent start --help 声明用于发现“这个 Herdr 版本明确支持启动哪些 Agent kind”。

herdr-mcp 对这三类 kind 做有界并集，再检查对应 executable 是否真实存在于 PATH，分别记录 herdr_startable、executable_available，并派生 available_for_start。只有 Herdr 自己声明可启动 + 本机 executable 存在 时，才认为这个 kind 可用于新任务分派。这样 herdr-mcp 不需要复制一份很快过期的 Agent kind 硬编码清单，同时仍能记录当前客户端的真实可用能力。

默认 scan 只有对通过副作用 smoke、进入显式 self-description adapter allowlist 的 Agent 才会执行有界 --version。--probe 额外运行有界、非交互的 --help adapter，只接受 Agent 自己 CLI 能明确证明的能力。发现 binary 但没有可信 adapter 时，只记录“已安装、未 probe”；--refresh 会显式重载 Herdr Agent manifest 并绕过已有 probe cache。

probe 子进程没有 stdin，超时上限为三秒，输出有大小上限，并且先清空继承环境，只恢复非敏感运行变量。API key、bearer token、provider credential 不会被继承。拿不到或存在歧义的字段继续保持 unknown；herdr-mcp 不会仅凭 Agent 名称猜 provider、model、vision、reasoning quality 或 code-edit 能力。

静态 evidence 放在 herdr-mcp config 目录下有界的 capability inventory 中。status、cwd、project、pane、workspace、session 等实时事实始终来自 Herdr/EventCache，inventory 不会成为第二套 live truth。herdr_inspect.capability_inventory.available_agents 默认暴露本机真实发现且可用的全部 kind；只有显式配置 HERDR_MCP_AGENT_ALLOW 时才缩小可见范围。发现某个 Agent 只代表它进入候选事实集，不代表固定角色，也不要求派工；Web planner 根据任务结构、实时负载、已验证能力和资源状态自行决策，质量、成本、延迟等拿不到证据的字段继续保持 unknown。

Web planner 的动态规划建议#

当前 workstation Runtime Execution Contract 为 epoch 5 / 18 tools，不新增专用 planning tool；first-party 公共 Edge contract 为 epoch 8 / 19 actions，其中 herdr_devices 只在 Edge 执行。herdr_skill 的 progressive bootstrap 会声明一个现有 herdr_call 可调用的本地只读方法：

复制herdr_call(
  method="herdr_mcp.planning.advise",
  params={
    "project_root":"/path/to/project",
    "requires_code_edit":true,
    "requires_shell":true,
    "independent_units":2,
    "ownership_isolated":true
  }
)

返回值把事实与决策分开：live compatible/rejected workers、scan 证明可启动但当前未运行的 Agent kind、direct deterministic option、parallelism opportunity，以及 workspace/pane/worktree/utility-pane 资源信息。它不会启动 Agent、不会创建 worktree、不会自动选择 worker。用户明确指定 target 时保留 target；任务要求的能力没有 evidence 时 fail closed；可选质量/成本/延迟证据缺失时继续保持 unknown。

Web planner 可据此决定直接执行、复用已有 Agent、创建一个新 lane，或在确实独立且 ownership 已隔离时并行。重复 utility pane、已有 idle/done Agent、已有 worktree 都作为“优先复用”的资源事实返回，清理仍由 planner 在确认任务完成后执行，不增加后台 cleanup daemon。

GitHub PR / Auto-merge 新鲜状态#

v0.4.5 继续通过现有 herdr_call 增加一个本地只读方法，不改变 workstation 的 18-tool contract：

复制herdr_call(
  method="herdr_mcp.github.status",
  params={
    "project_root":"/path/to/project",
    "pr_number":284,
    "previous_fingerprint":"sha256:..."
  }
)

该方法每次都直接使用 workstation 已登录的 gh CLI 读取 GitHub，因此会显式返回 source=local_gh_api、fresh=true 和 cache_policy=bypass_connector_cache。在刚修改仓库 Auto-merge 等设置之后，planner 不必依赖可能仍有缓存延迟的 Connector 投影。project_root 必须是当前 Herdr live snapshot 里的受管 Git root，且 origin 必须位于 github.com。

传入 pr_number 后会返回 PR state、merge state、Auto-merge request、required checks，以及 Deno Deploy 等 supplemental status。每次结果都有确定性的 fingerprint；继续监控时把它作为 previous_fingerprint 传回，如果状态没有变化，下一次只返回精简 summary 和 changed=false，不会重新输出整张检查表。监控正在运行的 CI 时，同时传入 wait_ms: 20000：工作站在本机完成这段有界等待，再在同一次调用里执行一次新的 GitHub 状态探测。状态变化时返回完整新状态；没有变化时返回精简的 changed=false 并标记 wait_timeout=true。20 秒上限为 Edge 的正常请求 deadline 和 GitHub 探测保留余量，也省掉 planner 单独 sleep 再查状态的一次往返。

Connector 与 Automation 凭据#

交互式 Connector 通过已登记 Device/operator 控制通道批准和撤销。批准只授予普通 MCP 访问，不会把 Connector 变成 fleet principal：

复制herdr-mcp connector approve <approval-request-id>
herdr-mcp connector list
herdr-mcp connector revoke <connector-id> --confirm

批准命令会交互式读取 6 位授权码，不要把授权码放进 argv 或 shell history。所有已登记 Device 都是平等的 Worker 管理通道，不存在 owner/member 设备层级。

GitLab CI 等无人值守调用方使用可独立 revoke 的 Automation Client：

复制herdr-mcp automation create --name "gitlab:group/project:prod" --device <device-id-or-unique-name>
herdr-mcp automation list
herdr-mcp automation rotate <svc_client_id> --confirm
herdr-mcp automation revoke <svc_client_id> --confirm

create 必须显式指定目标设备并保存 Worker 解析后的不可变 device_id，不会在 fleet 中静默替用户选机器。create 和 rotate 只显示一次 client_secret，应直接存进 CI secret manager；list 永远不返回 secret，只返回绑定设备和有限的签发统计。Automation Client 用 OAuth client_credentials 通过 client_id + client_secret 换短期 access token，只拥有绑定设备上的普通 MCP 权限，不拥有 fleet-admin 权限。

本机静态 bearer、公网 OAuth Connector 与 Automation Client 是三套边界。HERDR_MCP_TOKEN 只服务本机 TCP runtime，不要复制进 ChatGPT 或 GitLab CI。

完整接入见 ChatGPT Connector。

日志与健康检查#

复制herdr-mcp status
herdr-mcp logs
herdr-mcp logs -f

排障时最好先记录状态再重启。

建议组合：

复制curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8772/
herdr-mcp status
herdr-mcp logs

即使是 loopback，http://127.0.0.1:8772/mcp 也故意保持鉴权。第一方本机客户端可以从受保护的本地状态自动取得 runtime credential，让用户无需手工粘贴；裸 curl 或第三方 TCP client 必须显式带 bearer。官方浏览器插件不使用这个 TCP token，而是通过 Chromium Native Messaging 进入 mode-0600 的 extension.sock trusted IPC；这条通道本身 tokenless，并会剥离网页传入的 Authorization。

本机 HTTP 返回 200 或 401 都说明 runtime 在监听；连接失败才说明进程/端口层有问题。

Watchdog#

macOS 可以安装本机 watchdog：

复制herdr-mcp watchdog install
herdr-mcp watchdog status

它用于发现 herdr-mcp runtime 自身失联并按受控策略恢复，不把每一次 Herdr TaskGroup/ExceptionGroup 控制面毛刺都当成 daemon 必须重启。

因此 watchdog 是 runtime 可用性保护，不是“看到任何错误就全家桶重启”。

UI 语言#

复制herdr-mcp lang en
herdr-mcp lang zh
herdr-mcp lang ja

用于项目本机管理界面/相关 UI 语言设置。浏览器扩展也支持 en / 简体中文 / 日本語。

浏览器 Native Messaging Host#

浏览器扩展主链路需要本机 Native Messaging host：

复制herdr-mcp native-host install
herdr-mcp native-host status

安装后：

复制Chrome extension
  ↓ Native Messaging
herdr extension host
  ↓ local Unix socket
herdr-mcp runtime

浏览器不需要保存 Herdr bearer。

安装与 HUD 使用见 浏览器扩展。

Cloudflare Edge 凭据#

最小权限凭据#

复制bin/herdr-cloudflare-token --zone example.com --dry-run
bin/herdr-cloudflare-token --zone example.com
bin/herdr-cloudflare-token --zone example.com --verify-only
bin/herdr-cloudflare-token --zone example.com --rotate

用于创建/验证 Cloudflare Edge 所需的最小权限 deployment credential。具体权限和安全边界见 Cloudflare Edge 凭据。

Custom Domain#

复制bin/herdr-cloudflare-domain preflight
bin/herdr-cloudflare-domain status
bin/herdr-cloudflare-domain attach
bin/herdr-cloudflare-domain watch
bin/herdr-cloudflare-domain detach

用于把已验证 Worker 绑定到 Custom Domain。它和普通 Worker code deployment 是两个独立操作。

旧 Tunnel/CNAME 迁移#

复制bin/herdr-custom-domain-cutover preflight
bin/herdr-custom-domain-cutover run

只用于遗留架构从 CNAME/Tunnel 迁到 Worker Custom Domain。新安装不需要走这条路径。

详见 Cloudflare Edge 部署。

Runtime A/B#

Runtime generation manager：

复制bin/herdr-runtime-generation status

bin/herdr-runtime-generation register \
  --generation <id> \
  --endpoint http://127.0.0.1:8773/mcp \
  --runtime-version <version>

bin/herdr-runtime-generation activate --generation <id>
bin/herdr-runtime-generation rollback
bin/herdr-runtime-generation remove --generation <id>

它负责的是同一 contract epoch 内的本机 runtime generation 注册、切流和回滚。

核心原则：candidate 先运行、先健康检查、先验证 contract，再激活；不要先杀旧 runtime 再祈祷新 runtime 能起来。

详见 Runtime A/B。

Self Update#

复制bin/herdr-self-update

受监督自升级复用 generation 机制。它适合在同一 public contract 下更新实现，不用于偷偷跨 contract epoch。

如果 public tool catalog 发生不兼容变化，应走显式 contract migration，并在新的 ChatGPT conversation 验证新的 tool snapshot。

Workstation Link#

复制bin/herdr-link

herdr-link 是工作站到 Cloudflare Edge 的出站 WSS sidecar。正常情况下由系统服务管理，不需要日常手工运行。

它负责：

• workstation identity；
• 持久出站 WSS；
• 当前 active runtime 路由；
• runtime generation/version heartbeat。

它不是 MCP runtime 本身。

常用环境变量#

命令怎么选#

如果你发现自己需要大量直接调用 Herdr workspace/pane/agent 命令，请回到 Herdr 官方 CLI 文档；herdr-mcp 不重复维护那一套控制面。