命令行

本参考描述 Barn 0.9.0 发布候选。Barn 只使用新名称与全新的 Barn 状态， 不提供旧开发版本的兼容或迁移层。编写脚本前先核对 barn version， 发布进度见当前状态。

barn [--json|--yaml] [-v|--verbose] <command> [flags] [node...]

已安装的二进制是当前版本最准确的参考。每一条可见命令都自带操作边界与可复制样例：

barn --help
barn setup --help
barn image pull --help

直接运行 barn 会显示简短欢迎信息和下一步命令，以 0 退出， JSON/YAML 输出 actions[]。barn image 这样的裸命名空间仍以 2 退出，文本模式打印帮助，JSON/YAML 模式返回结构化用法错误。显式 --help 始终输出 供人阅读的帮助文本并以 0 退出。用 barn --version 或 barn version 查看构建身份。

命令

没有命令会隐式刷新 Catalog。update 获取配置仓库的 Catalog，校验并激活； image sync 是为精确 URL 或文件准备的显式恢复路径。普通命令只使用当前本地 Catalog。 两者都不更新 Barn 可执行文件。

常用命令提供作用域明确的短别名：

up、ssh、init、start、stop、restart、reload、provision、hosts、 completion 没有别名。请使用明确的 barn purge 拼写；rm 不是命令别名。 命名空间内部，hosts 与 network 的 install/uninstall 使用 i/u，network status 使用 st；image 使用 list=ls、info=in、pull=p、 prune=pr、sync=sy、import=i。image reset 保留 reset-manifest 作为兼容别名。

Barn 在选定的 BARN_HOME（默认 ~/.barn）中管理一套部署，其身份与 Inventory 所在目录无关。使用已应用状态的命令可在任意目录运行。配置来源由命令决定，-f 刻意不做全局参数：

没有配置文件且没有已应用部署时，交互式 up 可以生成默认配置；它也能准备缺少的宿主 依赖、恢复完整但未激活的 Barn 网络。该内部准备流程接受 setup 计划，sudo 仍可能 请求凭据；可先用 setup --dry-run 查看宿主计划。脚本应显式执行 setup --yes， 没有配置文件时无需另行 init。

关键参数

参数属于各自命令，下表列出容易混淆的作用域：

setup --dry-run 与 setup --yes 互斥。--cidr 用来调整生成模板的网段，不能重写显式 选择的 Inventory。validate --repo 是 0.9 候选版本新增参数，没有对应的 --mirror； 需要检查中国仓库时使用 --repo https://repo.pigsty.cc/barn。

0.9 候选版本中，network 与 hosts 的 install/uninstall 会在终端展示计划并询问确认 （安装默认同意，卸载默认拒绝）；非终端只展示计划，除非传入 --yes。 macOS 首次网络安装使用 setup；候选版本 的 network install 会在 sudo 提示前引导到该命令。--yes 接受 Barn 计划，不能提供 sudo 密码。

--mirror、--force、--rollback、--remove、--allow-downgrade、--sudo、 --delete-persistent、--purge 等低频或扩大风险边界的参数只保留长版本。读取 Inventory 的命令中 -f 始终选择文件；logs -f 保留惯用的 --follow。 -n 始终表示 --no-wait，-d 始终表示 Dry-run。

存在部署时，barn purge 与 barn destroy --force --purge 执行相同的整体处置， 且无需确认。它不接受节点或 Inventory，删除整套 Deployment、 持久盘、密钥、状态和默认 SSH Fragment，保留镜像与宿主网络。没有部署时幂等成功， 也可清除能够证明归属的保留盘；缺少状态文件绝不会授权按路径删除无法证明身份的遗留节点工件。 0.9 候选版本中，没有部署时的普通整体 destroy 也返回成功；但 destroy --force --delete-persistent 和 destroy --force --purge 会报错，提示改用 purge。

结构化失败（0.9 候选版本）

下列统一失败契约描述 Barn 0.9.0 发布候选。

普通失败会在 stderr 输出 error: <消息>；外部工具失败时附上它 stderr 的最后几行； 有明确下一步时再输出一行 next:。SSH 子进程退出失败不会重复打印错误，直接保留子进程输出。 如果命令没有提供更丰富的类型化结果，结构化模式会输出通用失败对象，包含 error、message，以及适用时的稳定 reason、next、operation_id 和外部程序详情 command（name、argv、exit_status、signal、timed_out、stderr），然后返回退出码。 已携带失败状态的结果后面不会追加第二份 JSON/YAML 文档。 通用对象的 error 使用下方表格中的固定类别；recreate_required 和 nodes_removed 改为 error: "conflict" 下的 reason，旧的 resource_conflict 类别改为 resource。

非零退出不保证 stdout 一定是这个通用对象。 doctor、network、provision、 生命周期操作与远端命令可以返回各自的报告结构。SSH 子进程退出在内部归类为 remote_exit， 但公开结果包含 success、exit_code、stdout、stderr 等字段，可选 error 也不服从 通用错误分类契约。自动化应始终保留进程退出码，再按具体命令解释 payload。

生命周期结果

plan 是只读操作，即使 action 为 recreate 或 blocked-removal 也返回成功；自动化必须 检查 action 与 create、start、recreate、missing、blocked 字段。对于 Catalog 镜像，计划只读取本地配置和 Catalog，无需先安装 QEMU 或宿主网络；已注册的 local-* 镜像还会校验缓存，需要 qemu-img。计划不会下载镜像；它显示精确镜像、资源总量、变更原因 和磁盘影响。0.9 候选版本还逐项列出数据盘，包括隐式的 128 GiB /data。 宿主能力与地址可用性由 up 在执行前检查。up 会创建缺失节点、启动已停止 节点、复查运行中节点的就绪状态，并根据完整的 applied deployment 重写 Barn 安装的 SSH 客户端配置；recreate 同样执行全量刷新，节点级 destroy 删除旧条目，整体 destroy 移除该配置。start 启动已停止节点并复查运行中节点的就绪状态，start 与 restart 也会刷新 SSH 别名。 破坏性 drift 返回冲突，并给出下一步命令：先 barn plan，再 barn recreate <node> 或 barn destroy <node>；终端上这两条命令会要求输入确认词，--force 仅用于脚本。 如果 VM 生命周期成功但 SSH 客户端配置无法写入，命令会给出警告并返回成功； barn ssh 仍然可用。结构化输出通过 warnings[] 报告集成问题。 0.9 候选版本不修改符号链接或硬链接形式的 ~/.ssh/config，会发布独立配置片段， 并提示需手动加入的 Include 行。

就绪边界是管理 SSH 可用。可选初始化问题通过 nodes[].warnings 报告，已完成的恢复 操作（包括数据盘重置）写入 nodes[].repairs。客机可用但有这些限制时返回 0；重复 up 会重试未完成步骤，无需重启运行中的 VM。要求全部配置功能可用的自动化应检查警告字段。

生命周期批处理出现可隔离的节点级失败时，即使所有选中节点都失败也可能返回 5，并报告 N of M node(s) failed: <node> (<stage>: <error>); ...。常见阶段包括 prepare、start、 readiness、bootstrap、guest-setup、stop、status；readiness 或 bootstrap 失败会追加 run \barn logs ` for the guest console。结构化输出携带 failures[]（node、stage、error，**0.9 候选版本**还有可选 reason）；当 –rollback清除了 从未提交节点的 prepare 产物时，还会带上rolled_back`。参见 节点未就绪。

status 默认展示节点、状态、IP、精确镜像和 CPU/内存；--verbose 展示 SSH 端口、 架构、加速器与 PID。TCG 在普通文本中也有标记。一个节点异常时，仍保留其他节点的 状态，并返回 5；结构化输出包含逐节点 error 和 failures[]。running 表示 VM 正在运行，不代表本次 status 检查了 guest 就绪状态。

启动命令完成后还会刷新运行中 guest 的 Barn hosts 和控制节点 SSH 配置；停止中的 节点在下次启动时更新。--no-wait 会跳过 guest 就绪检查、恢复和刷新，随后执行 up 补齐。 局部 recreate 若仍受未选节点的配置变化影响，会在停机、删盘前拒绝；按提示一次选择 需要重建的节点。

控制节点中由 Barn 管理的 SSH 条目不固定 guest 主机密钥，也不写入 known_hosts， 因此重建实验节点后可以直接连接。用户自行添加的 SSH 配置会保留。

恢复行为

up、start 按节点隔离宿主共享目录 缺失的影响；up 在新节点准备失败后仍会启动独立的已有停止节点。部分成功保留退出码 5 和成功节点。重试提示保留配置文件、镜像仓库及适用参数，start 的重试仍为 start。

setup 与随后生命周期重试使用同一个 operation_id。首次 setup 失败、尚无部署状态时， 也可通过 barn logs --source events --json 读取有大小上限的阶段日志。setup 日志不记录 命令参数和认证信息，详细根因以命令输出为准；setup --dry-run 不写日志。 destroy --delete-persistent 与 purge 成功摘要只描述最终删除、保留的资源；purge 仍保留镜像缓存和宿主网络。 先删除某个节点后留下的受管持久盘，不再阻断其余节点的销毁。普通 destroy 继续保留 这些盘，只有显式删除持久盘或 purge 才会移除它们。

macOS 新网络安装先完成 Homebrew 发现/安装或固定归档下载，再申请管理员认证。 这避免了 Homebrew 清除先前 sudo 凭据导致的安装失败，不扩大特权操作范围； 下载失败时不会提前要求输入密码。

中断操作恢复（0.9 候选版本）

候选版本会把已被无关进程复用的 QEMU PID 识别为节点停止。stop 中断而 VM 仍运行时， 状态会恢复为 running；其他未完成过渡会指出用于完成它的命令。destroy 会自行处理 中断过渡。首次 up 失败后可以编辑 Inventory 再重试，因为未提交产物按照日志记录回滚。

日志与环境变量

logs 默认读取客机串口；--source qemu 读取 QEMU 诊断，--source events 读取有大小 上限的部署事件日志。使用 --follow 时，文本流式输出字节，JSON 输出 NDJSON 记录， YAML 输出文档流。0.9 候选版本将普通 events/qemu 日志读取显示为可读记录， 只有 --verbose 才显示 QEMU argv。

SSH 透传与命令补全

barn ssh [node] [--] [command ...] 打开会话或运行可选命令； barn exec [node] [--] <command ...> 必须给出命令并透传退出码。-- 之前的展示参数 属于 Barn。ssh 中 -- 之后的参数会像普通 SSH 一样以空格连接，再交给远端 shell 解释； exec 保留多个参数的边界，需要 shell 展开或管道时请显式使用 sh -c； 单个命令字符串仍保留 shell 简写行为。 有 -- 时，其前面只能是空或一个已知节点。为方便交互使用，也接受省略 --：已知 首参数选节点，否则把整段当成默认节点上的命令，并显示 warning。0.9 候选版本会检查 包含数字或 - 的首参数是否像节点名误拼：长度不超过四个字符时最多一个编辑距离， 更长时最多两个。符合时会拒绝执行；ls、df、wc 等普通命令仍可运行。脚本中请明确写 --。

加载 barn completion bash|zsh|fish|powershell 可获得命令与作用域准确的参数补全， 同时补全命令别名、模板、镜像别名、枚举参数，以及从期望/已应用规格只读解析出的节点名。 0.9 候选版本还会让 -f 补全只列出 YAML 文件。

退出码

此表列出 Barn 0.9.0 发布候选的退出码契约。缺少配置、未知镜像均为 usage（2）； setup/network 失败按原因区分为 runtime（1）或 capability（3）。

0.9 候选版本中，修改类命令遇到另一个 Barn 命令持有部署锁时，最多等待 10 分钟 并指出对方；超时以 4 退出，reason 为 deployment_busy。status、ssh、exec、 ssh-config、hosts 不等待。status 在显示已记录状态时通过 note 报告并发操作； 这不代表该部署操作已完成。

ssh 与 exec 原样透传 SSH 子进程退出码，包括 255；255 可能是 SSH 连接失败， 也可能是远端命令返回该值。文本、JSON 与进程退出码保持一致。