05/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） |
| 更新 | collie update | 准备当前大版本的最新发布版本、切换至该版本、重启并验证（--check 执行预检，--status 输出报告，--major 跨大版本升级） |
| 回滚 | collie update --rollback | 恢复上一版本（在 Herdr 管理的代码库中不可用，因其未暂存旧版本） |
| 卸载 | collie uninstall | 删除服务；保留 .env 和安装内容 |
| 配对 | collie pair | 输出一个 8 位配对码和一个二维码，有效期 10 分钟；扫描二维码可打开“Settings → Paired devices”并自动填入配对码，也可手动输入配对码以将其 已配对 |
| 设备 | collie devices list · collie devices revoke <label> | 列出 / 吊销已配对的设备 |
| 链接 | collie link · collie unlink | 将 collie 添加到 PATH (下方) |
| 日志 | collie logs | 跟踪 journal / 日志文件 |
| 语音 | collie stt setup · stt test · stt status · stt off | 配置 / 检查 / 禁用 语音输入 |
| 推送密钥 | collie push-keys | 将 VAPID 密钥对生成到 .env |
| 推送测试 | collie push-test | 发送一条通知以验证其正常工作 |
CLI 还包含 build、serve、unserve、doctor 和 pack …，用于执行低频任务。
start 和 status 都会输出 Collie 正在运行 横幅：一个健康标记和版本号，接着是一行 service、一行 local 和一行 tailnet。首次运行 完整展示了该内容，包括健康检查失败时打印的替代内容。报告的版本读取自所提供 bundle 的时间戳，反映了当前处于活动状态的构建。
Ink 或纯文本。 当 stdout 为 TTY 时，start、status、doctor、pack add 和 pack status 命令会渲染交互式终端 UI。传入 --plain，或将输出重定向到管道、文件、systemd journal 或 CI runner 时，会回退到原始单行文本输出。
将 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 plugin install AltanS/collie 或 herdr plugin link 创建的 仅适用于由 Herdr 管理的安装。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 没有对应的插件 action，因为它们需要终端、位置参数，或两者都需要。请将它们作为 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/的已编译二进制文件中只实现一次。