命令参考

逐项介绍 Barn 全部命令的语法、局部选项、默认值、使用示例与版本范围。

3 分钟阅读

从下表选择命令，查看参数、完整局部选项、示例与操作范围。组织方式参考 PIG 的命令索引与命令组详解；结构化输出及退出码见 CLI 契约，清单字段见配置参考。

版本基线

本参考对应 2026-11-12 发布的 Barn 1.2.0，源码为 90f6158。中英文页面均已对照 CLI 帮助核对，覆盖 57 个操作命令与 174 项局部选项。

标记	可用范围	行为
1.1.0	1.1.0 与 1.2.0 均支持的选项	1.1.0 默认 2 vCPU / 4 GiB，通过清单调整 CPU/内存
1.2.0	1.2.0 新增	规格选项与环境变量、`vm_scale`、根盘扩容、生命周期 `--parallel`、`vm_hosts` 和 `hosts install -f`；默认规格改为 1 vCPU / 2 GiB

升级时如需保留旧默认值，请显式设置 vm_cpu: 2、vm_mem: 4GiB，并检查 barn plan。已应用 VM 的资源会保留到显式执行资源变更操作为止。用 barn version 和 barn COMMAND --help 核对已安装构建；另见发布说明与发布验收。

命令索引

任务	命令与详细参考
准备环境	setup、init、validate、doctor
规划与创建	plan、up
启停节点	start、stop、restart、reload
调整与检查	resize、recreate、status
删除部署	destroy、purge
访问 Linux 客机	ssh、exec、logs、provision、ssh-config
发布宿主名称	hosts install、hosts uninstall
刷新目录	update、image sync、image reset
管理 Linux 镜像	image list、info、pull、import、prune
维护镜像仓库	repo scan、build、verify
宿主网络	network status、install、uninstall
原生 macOS VM	mac ls、up、start、stop、restart、configure、recreate、destroy
Mac 访问	mac open、ssh、exec、password、ssh-config、logs
Mac 准备	mac setup、doctor、image ls、image update、image prune
CLI 工具	version、completion、help

全局选项

barn [--json|--yaml] [-v|--verbose] COMMAND [arguments] [local options]

选项	含义
`-h`、`--help`	显示所选命令的可读帮助，退出 `0`
`--json`	stdout 输出结构化 JSON，进度与诊断保留在 stderr
`--yaml`	stdout 输出结构化 YAML，与 `--json` 互斥
`-v`、`--verbose`	向 stderr 输出有界诊断信息
`--version`	根命令的版本快捷选项；结构化版本报告用 `barn version --json`

全局输出选项可放在子命令前后，但必须在 ssh、exec 使用的远程命令分隔符 -- 之前。-f、-I、-A、-p、--yes 都是局部选项，以对应命令的表格为准。logs -f 表示跟随日志，mac logs -n 表示行数。长布尔选项支持 =true 或 =false。

BARN_OUTPUT、BARN_VERBOSE 设置输出默认值。BARN_HOME 选择私有状态目录，默认 ~/.barn，跨目录操作时建议使用绝对路径。Linux 与 Mac 机器共用数据根目录，但生命周期相互独立。详见环境变量与退出码。

barn 与帮助

barn
barn --help
barn help resize
barn image pull --help
barn --json

无参数时，文本模式打印完整帮助并退出 0，JSON/YAML 模式返回建议操作 actions[]。显式帮助始终输出可读文本。image、repo、network、hosts、mac image 命令组要求子命令，缺少时退出 2；mac 是例外，默认执行 mac ls。Linux 和 Intel Mac 的根帮助隐藏 mac，但仍可显式查看 Mac 命令帮助。

简写在父命令范围内生效，例如 barn im ls 等同 barn image list，barn mac st 等同 barn mac ls；各命令页列出了对应别名。purge 没有 rm 别名。