18/Documentation
命令
每个 collie 子命令、将 collie 添加到 PATH，以及在 Herdr 托管安装中对应这些子命令的 Herdr 操作
每个动词都使用格式 collie <verb>。这是所有安装中的规范语法，直接在二进制文件（cli/）中实现。将 collie 添加到 PATH（下方）之前，先在仓库根目录运行 bin/collie <verb>。在 Herdr 管理的安装中，这些相同的动词会注册为 Herdr 动作（下方），行为完全一致。
如果主机运行多个实例，请在每个动词前加上 COLLIE_INSTANCE=<name>。参见 单台主机上运行多个 Collie 实例。
| 动词 | 命令 | 作用 |
|---|---|---|
| 启动 | collie start | 按需构建、提供服务并输出 URL |
| 停止 | collie stop | 暂停桥接；不删除任何内容 |
| 重启 | collie restart | 停止，然后启动 |
| 状态 | collie status | Collie 正在运行 横幅与 URL |
| URL | collie url | 输出 tailnet URL |
| 二维码 | collie qr | 将同一 URL 显示为可扫描的二维码 |
| 版本 | collie version | 当前运行的版本（0.x.y+sha） |
| Skill | collie skill | Collie 面向 agent 的简报，供终端中运行的 AI 编程 agent 参考（亦见 collie --skill）。collie skill install、uninstall、sync、status 和 print 管理 agent 指令文件中的 walky talky skill；collie update 在每次更新（安装 skill）后运行 sync |
| 文档 | collie docs · collie docs <name> · collie docs --all | 这些页面直接由二进制文件本身输出 |
| 更新 | collie update | 准备当前大版本的最新发布版本、切换至该版本、重启并验证（--check 执行预检，--status 输出报告，--major 跨大版本升级） |
| 回滚 | collie update --rollback | 恢复上一版本（在 Herdr 管理的代码库中不可用，因其未暂存旧版本） |
| 卸载 | collie uninstall | 删除服务；保留 .env 和安装内容 |
| 配对 | collie pair · collie pair --expires <duration> | 输出一个 8 位代码和一个二维码，有效期 10 分钟；扫描二维码打开 Settings → System → Paired devices 并自动填入代码，或手动输入代码以将其 已配对。若不带 --expires，token 永不过期，命令也会提示这一点；若带该参数（12h、30d、2w），命令会输出 token 申领后失效的日期。脚本使用自己的标签申领代码（例如 script），并配对一次（为设备设置过期时间） |
| 设备 | collie devices list · collie devices revoke <label> · collie devices set-expiry <label> <duration> · collie devices clear-expiry <label> | 列出/撤销已配对设备，或修改设备的 过期。list 显示各设备的过期状态为 no expiry、expires <date> 或 EXPIRED <date>。set-expiry 从当前起计算新的有效期；clear-expiry 将其移除。标签必须精确匹配，或者在仅有一台设备符合时忽略大小写匹配 |
| 链接 | collie link · collie unlink | 将 collie 添加到 PATH (下方) |
| 日志 | collie logs | 实时查看服务日志 (tail) |
| 配置 | collie config show · collie config check · collie config init | 输出各项配置及其来源、校验配置文件，或写入带注释的 config.toml（配置文件） |
| 持久 agent | collie durable attach <name> --socket <path> · collie durable attach <name> --url <url> --token-env <VAR> · collie durable detach <name> · collie durable list | 向 sources.json 添加 durable agent、将其删除，或列出每个 durable agent 及其在运行中 bridge 里的状态。attach 和 detach 会在下次重启时生效，或者加上 --restart 立即生效。选项、输出和退出码：持久 agent |
| Walky talky | collie walky who · collie walky send <address> <text> · collie walky reply <id> <text> · collie walky inbox · collie walky status <id> | 从终端向 agent 会话发送消息，或在 agent 之间发送消息（Walky talky） |
| 语音 | collie stt setup · stt test · stt status · stt off | 配置 / 检查 / 禁用 语音输入 |
| 推送密钥 | collie push-keys | 将 VAPID 密钥对生成到 .env |
| 推送测试 | collie push-test | 发送一条通知以验证其正常工作 |
CLI 还包含 build、serve、unserve、doctor 和 crew …，用于执行低频任务。
start 和 status 都会输出 Collie 正在运行 横幅：一个健康标记和版本号，接着是一行 service、一行 local 和一行 tailnet。首次运行 完整展示了该内容，包括健康检查失败时打印的替代内容。报告的版本读取自所提供 bundle 的时间戳，反映了当前处于活动状态的构建。
Ink 或纯文本。 当 stdout 为 TTY 时，start、status、doctor、crew add 和 crew status 命令会渲染交互式终端 UI。传入 --plain，或将输出重定向到管道、文件、systemd journal 或 CI runner 时，会回退到原始单行文本输出。
collie doctor 说明了它读取的状态。 它的第一行标明了实例名称（default 或 COLLIE_INSTANCE 中的名称）以及它读取的状态目录。如果您在单台机器上运行两个 lane，请在采信其余内容前检查该行，因为具有错误 COLLIE_INSTANCE 的 shell 会读取错误的 lane。--json 在 collie 条目上提供了与 instance 和 stateDir 相同的两个值。
collie doctor 列出您的 agent 程序。 Collie 拥有输入 profile 的每个程序都会获得一行 harness-<name>：Collie 会在您登录 shell 的 PATH 上运行的文件、它输出的版本以及 profile 对该版本的判定。高于已验证范围的版本仅作为注释提示，因为轮次中的发送仍然可信。当文件能解析但无法读取其版本时（例如位于 PATH 首位但依赖 $HOME 的包装器，或是损坏的安装），该行会发出警告：在成功读取版本之前，Collie 会将发送给该程序的每次操作都视为临时操作。未安装的程序显示 not installed。在 --json 中，每行还带有 harness、binary、version 和 profileStatus。
该行指明了您 PATH 上的副本，因为 collie doctor 没有可查看的窗格。Herdr 上的发送会查询在其窗格中运行的程序，因此运行另一个副本（通过其完整路径启动或安装在项目中）的窗格会在其回执上显示该副本的版本。
将 collie 添加到 PATH
运行 collie link 以发布 ~/.local/bin/collie：
bin/collie link # ~/.local/bin/collie → <checkout>/bin/collie
collie status # from anywhere
bin/collie unlink # take the name back down它会创建一个 指向签出目录二进制文件的符号链接，因此后续的 collie build 更新无需额外操作即可立即生效 (ADR 0021)。该命令会替换来自其他 Collie 签出目录的现有链接，并输出被覆盖的链接。若该路径存在非 Collie 文件，它将拒绝覆盖。仅当符号链接指向 你的 当前签出目录时，unlink 才会将其删除。
如果 PATH 中缺少 ~/.local/bin，link 会发出警告并退出。它从不修改 shell 配置文件。运行 collie doctor 检查 path-link 这一行，查看独立的 collie 命令解析到哪个签出目录。
Herdr 操作
仅适用于由 Herdr 管理的安装 使用 herdr plugin install AltanS/collie 或 herdr plugin link 创建。Herdr 是 Collie 支持的五种多路复用器之一。这些操作直接映射到适配器：每个操作都会将动词转发到上表中记录的同一个 collie 二进制文件。在通过 scripts/install.sh 创建的二进制安装中，插件操作不存在，collie <verb> 是唯一的语法。
Collie 会在 herdr-plugin.toml 中注册这些操作。使用 herdr plugin action invoke <id> --plugin herdr.collie 调用它们，或使用 herdr plugin action list --plugin herdr.collie 查看它们：
<id> | 等效谓词 | 作用 |
|---|---|---|
start | collie start | 按需构建，启动服务，tailscale serve，打印 URL + 横幅 |
stop | collie stop | 暂停桥接；不删除任何内容 |
restart | collie restart | stop + start |
status | collie status | Collie 正在运行 横幅：就绪状态 ✓/⚠、版本、URL |
url | collie url | 输出 tailnet URL |
version | collie version | 输出运行中的版本（0.x.y+sha） |
update | collie update | 更新检出分支（pull，或者 fetch 并重新分离 HEAD）+ 重新构建 + 重启 |
uninstall | collie uninstall | 销毁服务（保留 .env + 检出目录） |
push-keys | collie push-keys | 将 VAPID 密钥对写入服务读取的 .env |
push-test | collie push-test | 向每个已订阅的设备推送一条通知 |
qr、pair、devices、link、logs、stt 和 config 没有对应的插件操作，因为它们需要终端、位置参数，或两者都需要。请将它们作为 collie <verb> 运行。
Herdr action 返回 Herdr 的 JSON 封包，而不是终端横幅。 使用 herdr plugin log list --plugin herdr.collie 查看 action 捕获的 stdout，或直接运行 collie <verb> 将输出打印在行内。herdr plugin list --json 的输出反映的是在 plugin link 期间缓存的版本，而不是当前活跃版本。对于已关联的克隆副本，update 会自动重新关联以修复缓存。你可以使用 herdr plugin link "$(pwd)" 强制执行此操作。Herdr ≥0.8.0 会在每次调用时重新从磁盘读取清单。
注意。scripts/collie-ctl.sh <verb>仍然受支持。它充当引导 shim：定位 Bun，如果检出目录中缺少bin/collie则进行编译，并传递 argv。全新链接的克隆使用此路径构建其初始二进制文件。Herdr 操作继续指向此脚本，因为 Herdr <0.8.0 会冻结安装时缓存的操作定义（ADR 0006）。每个动词在cli/的已编译二进制文件中只实现一次。