命令参考

• 1: 准备与工具
• 2: Linux 生命周期
• 3: 客机访问与 hosts
• 4: 镜像命令
• 5: 仓库命令
• 6: 宿主网络命令
• 7: macOS 命令

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

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

1 - 准备与工具

生成清单、准备宿主、校验配置，以及查看版本和生成补全脚本。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn setup

barn setup [meta|dual|trio|full] [flags]

准备宿主软件包、固定 IP 网络、镜像与所选清单，然后运行 barn up 创建 Linux VM。meta、dual、trio、full 模板分别包含 1、2、3、4 个节点；未指定模板或 -f 时复用发现的清单，没有清单才生成 meta。-c 与规格选项用于生成模板，显式规格选项不能用来改写已有清单；1.2.0 复用清单时也忽略规格环境变量。

--dry-run 预览整个事务。执行需要终端确认或 --yes，系统提权仍可能询问密码。新生成且未经编辑的默认模板遇到子网冲突时，setup 可以选择空闲私有 /24，并将原模板备份为 barn.yml.before-network-change；显式清单保留原子网。Linux 宿主运行异架构客机时，需要另外安装目标 QEMU 模拟器与固件。

别名：s。

barn setup --dry-run
barn setup full -I el9 --yes
barn setup -f pigsty.yml --yes
barn up

barn init

barn init [meta|dual|trio|full] [flags]

生成兼容 Pigsty 的 YAML 清单，默认在 ./barn.yml 写入单节点 meta 模板，控制节点地址为 .10；dual、trio、full 依次增加 .11、.12、.13 节点。覆盖已有文件必须加 --force，-o - 将清单输出到 stdout。本命令不下载镜像或准备宿主。

稳定版 1.1.0 每节点默认 2 vCPU、4 GiB，1.2.0 为 1 vCPU、2 GiB；两者均默认 64 GiB 根盘和独立的 128 GiB /data 盘。1.2.0 模板保存六项规格字段，包括 vm_scale。详见规格默认值。

barn init
barn init full -I el9 -A amd64 -o lab.yml
barn init dual -c 10.20.30.0/24 -o -

barn validate

barn validate [flags]

读取清单并校验 Barn 使用的字段，输出解析后的节点；不接受节点位置参数。未指定 -f 时依次在当前目录寻找 barn.yml、barn.yaml、pigsty.yml、pigsty.yaml；找不到清单就报错，即使存在已应用状态也不回退。覆盖参数仅对本次校验生效，--json 可查看解析后的规格，与现有部署比较则用 plan。

别名：v。

barn validate -f lab.yml
barn --json validate -f lab.yml -I u24 -A arm64

barn doctor

barn doctor [flags]

检查 QEMU、原生加速、固件、OpenSSH、短暂的加速启动测试和宿主网络；不接受清单或节点参数。缺少计算能力时命令失败，尚未准备网络则作为提示报告。网络细节用 barn network status 检查，原生 macOS VM 用 barn mac doctor。

别名：dt。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn doctor
barn --json doctor
barn doctor --verbose

barn version

barn version [flags]

输出版本、源码提交、构建时间、宿主操作系统与架构。1.2.0 通常显示 dev，正式版本标识来自构建时写入的信息。核对文档或提交问题时保留这份输出，也可用根命令的 barn --version。

别名：ver。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn version
barn --json version

barn completion

barn completion [bash|zsh|fish|powershell] [flags]

必须指定 bash、zsh、fish 或 powershell 中的一种 shell，将补全脚本输出到 stdout；命令本身不安装脚本。补全涵盖各命令的选项、模板、镜像别名与可读取的节点名，升级 Barn 后应重新加载。加载 shell 代码时使用文本输出。

除 --help 外没有局部选项，仍可使用全局输出选项。

source <(barn completion bash)
barn completion zsh > "${fpath[1]}/_barn"
barn completion fish > ~/.config/fish/completions/barn.fish
barn completion powershell

实现依据

command_setup.go · command_misc.go · command_root.go

发布源码与相对 1.1.0 的变化见版本基线。

2 - Linux 生命周期

规划、创建、启停、调整、查看和显式删除 Linux 虚拟机。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

节点参数使用 meta、node-1 等解析后的名称，省略时选择该命令清单或已应用范围内的全部节点；IP、组名、vm_alias 均不能作为选择器。plan、up、reload、resize、recreate 依次读取 -f、当前目录清单、已应用状态，其他生命周期命令直接使用已应用状态。

规格覆盖、缩放和环境变量见配置参考。1.2.0 并发选项只适用于下文列出 --parallel 的命令，plan、resize、status 不接受它。结构化结果与退出码见 CLI 契约。

barn plan

barn plan [node...] [flags]

将有效期望清单与已应用状态比较，输出精确镜像、资源、逐盘动作，以及需要创建、调整资源、重建、启动或显式移除的节点，不改变 VM 或下载镜像。目录镜像仅需本地元数据，具名本地镜像还需要 qemu-img。

退出码 0 表示成功生成计划，也可能是因清单遗漏节点而阻塞的计划；脚本需检查 action、blocked 和变更数组。显式选择节点时保留其他节点的已应用定义。结果格式见计划输出。

别名：pl。

barn plan
barn plan -f pigsty.yml meta
barn --json plan -I u24 -A amd64

barn up

barn up [node...] [flags]

创建缺失节点、启动已停止节点，并在保留健康 VM 进程的同时重试未完成的客机配置。默认等待管理 SSH 就绪，随后更新宿主 SSH 别名、客机 hosts 与控制节点 SSH 条目；非致命客机配置问题放入 warnings，已就绪节点仍视为成功。

首次交互运行时可以准备缺失的宿主依赖；清单与部署状态都不存在时会生成 meta。脚本应先运行 setup --yes。已有节点的定义变化需用 resize 或 recreate，清单遗漏的节点需显式 destroy。--rollback 仅清理本轮准备失败节点中尚未提交且可安全回收的制品。

barn up
barn up -f pigsty.yml meta
barn up --mirror --rollback
barn up meta --no-wait

barn start

barn start [node...] [flags]

按已应用状态启动所选已停止节点并等待 SSH，使用同一 BARN_HOME 时可从任意目录执行，不读取清单或创建新节点。启动会刷新 SSH 访问配置；已经运行的 VM 需要补做客机配置时用 up。共享目录不可用只影响对应节点，独立节点继续执行。

barn start
barn start meta --no-wait

barn stop

barn stop [node...] [flags]

核验已记录的进程身份后停止所选 Linux VM，保留根盘、数据盘、密钥与部署状态。未指定名称时停止整套 Linux 部署；原生 macOS VM 和宿主网络分别由各自命令管理。

barn stop meta
barn stop

barn restart

barn restart [node...] [flags]

使用已应用状态停止并重新启动已有节点，不读取清单修改。需要重新读取清单用 reload，应用已有节点的定义变化用 resize 或 recreate。默认等待 SSH，--no-wait 可跳过等待。

barn restart
barn restart meta --no-wait

barn reload

barn reload [node...] [flags]

先校验期望规格与启动依赖，通过后才停止所选节点并按 up 流程收敛，可以创建清单中新增加的节点。需要调整资源或重建的变更，以及清单遗漏的已应用节点，都会在停止任何 VM 前阻止执行。仅按已记录配置重启时用 restart。

barn reload -f pigsty.yml
barn reload meta --mirror

barn resize

barn resize [node...] [flags]

调整 CPU 与内存，保留 VM 身份、磁盘与 SSH 密钥。支持的增加操作使用热插拔，减少资源或不支持在线修改时使用停机再启动。稳定版 1.1.0 从清单读取 CPU/内存变更；镜像、架构、数据盘、网络、共享目录、节点创建和移除均不能通过 resize 应用。

1.2.0 还接受资源参数，并可用 -D 128GiB 原地扩容根盘：停止 QEMU、扩展镜像、启动客机扩展并核验最后一个普通 ext4/XFS 根分区，原先停止的 VM 最后恢复为停止状态。目标只能增加，且须对齐 512 字节。中断后用同一目标重试；不支持缩小、LVM、加密根盘或非末尾分区。详见根盘扩容与恢复。命令行覆盖不改写清单。

barn plan -f pigsty.yml meta
barn resize -f pigsty.yml meta
barn --json status meta

barn recreate

barn recreate [node...] [flags]

按期望清单替换所选 VM，会删除这些节点的根盘与非持久数据盘，并重新挂接兼容的持久盘。先用 plan 检查范围；终端要求输入 recreate，脚本必须传 --yes 或 --force，没有 -y 简写。

不选节点时应用整个清单；清单遗漏已有节点会在停止 VM 前报错，需先显式销毁该节点或将它加回清单。选择性重建保留其他节点，成功后也会刷新 SSH 访问配置。

别名：rc。

barn plan meta
barn recreate meta
barn recreate -f pigsty.yml meta --yes

barn status

barn status [node...] [flags]

检查已记录的节点配置与当前 QEMU 进程身份，无需位于清单目录。running 表示已核验 VM 进程存在，不能据此判断 SSH 就绪。--verbose 增加运行时细节，--json 返回节点记录、正在进行的操作说明和失败信息。退化节点可能使命令退出 5，健康节点仍会列出。1.2.0 文本输出使用 2c4g 这样的紧凑 SPEC 值。

别名：st。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn status
barn status meta --verbose
barn --json status

barn destroy

barn destroy [node...] [flags]

删除所选 VM，未指定节点时删除整套部署。根盘与非持久数据盘会被删除，持久盘默认保留；终端要求输入 destroy，脚本必须传 --yes 或 --force，没有 -y。

--delete-persistent 和 --purge 仅支持整套部署，后者还删除部署密钥与状态。镜像缓存、宿主网络和原生 Mac VM 保留。删除控制节点后，第一个剩余节点接任控制角色；随后更新 admin_ip 并运行 up 配置其控制 SSH 访问。

别名：de。

barn destroy meta
barn destroy --yes
barn destroy --yes --purge

barn purge

barn purge [flags]

立即删除整套 Linux 部署，包括根盘、持久数据盘、密钥、状态和默认 SSH 配置片段，不接受节点名或读取清单。没有 --yes、-y、--force 选项；需要先审阅范围时用 --ask，输入 y/yes 确认，回车取消。

镜像缓存、宿主网络和 Mac VM 保留。部署不存在时幂等成功，遗留制品身份不明时仍需核验。1.2.0 的 --parallel 控制清理过程中的节点并发。

barn purge --ask
barn --json purge

实现依据

command_lifecycle.go · main.go

发布源码与相对 1.1.0 的变化见版本基线。

3 - 客机访问与 hosts

连接 Linux 客机、执行脚本、读取日志，以及发布 SSH 和 hosts 条目。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn ssh

barn ssh [flags] [node] [-- command...]

打开所选已准备节点的交互 SSH 会话，默认选择已准备的控制节点，否则选第一个已准备节点。远程命令必须放在 -- 后，参数会像普通 ssh 一样合并后交给远程 shell 解析；Barn 选项放在分隔符前。节点参数必须是解析后的节点名，不能使用 IP、别名或组名。

远程命令的退出码原样传回。结构化交互 SSH 将会话输出发送到 stderr，最终报告写入 stdout。详见 SSH 参数规则。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn ssh
barn ssh meta
barn ssh meta -- 'df -h /data; id'

barn exec

barn exec [flags] [node] -- command...

在所选已准备节点运行一个远程命令，默认节点选择规则与 ssh 一致。必须使用 --，首个命令参数不能为空；分开的参数保留空格、引号以及后续空值。管道、重定向和变量展开请用 sh -c，也兼容将单个完整字符串作为 shell 命令。

文本模式转发子进程输出与退出码；结构化结果包含 success、exit_code、stdout、stderr。远程非零退出码原样返回，应先检查报告再判断是否属于 Barn 自身错误。

别名：ex。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn exec meta -- hostname
barn exec meta -- printf '<%s>\n' 'a b' ''
barn --json exec meta -- sh -c 'echo out; exit 17'

barn logs

barn logs [node] [flags]

读取所选节点的串口或 QEMU 诊断日志，默认选已准备的控制节点或第一个已准备节点。--source events 读取部署级有界事件日志，不接受节点参数，可在部署状态建立前使用。跟随模式持续输出流，-f 在这里表示跟随日志，不是清单文件。QEMU 参数仅在详细输出开启时显示。

别名：l。

barn logs meta
barn logs meta --source qemu
barn logs --source events --follow
barn --json logs meta --follow

barn provision

barn provision [node...] [flags]

通过已验证的部署 SSH 连接，将本地 Bash 脚本流式发送给所选运行中节点；未选节点时针对全部节点。脚本不会作为文件留在客机，执行记录包含脚本摘要；命令不创建或启动 VM。

必须指定 --script，默认串行执行，整个操作默认超时一小时。此处 --parallel 0 无效，与 1.2.0 生命周期并发规则不同。--sudo 在客机使用非交互的 sudo -n，需确保客机用户已有权限。结构化输出可以检查各节点的执行结果与失败。

barn provision --script ./check.sh meta
barn provision --script ./bootstrap.sh --sudo --parallel 2 --timeout 30m

barn ssh-config

barn ssh-config [node...] [flags]

默认打印 Linux 部署的 OpenSSH 配置片段。--install 写入片段并在 ~/.ssh/config 加一条 Include，打印和安装都可选节点；--remove 只移除指定的 Barn 片段，不依赖部署状态，也不接受节点名。安装与移除选项互斥。

默认前缀为 barn，片段路径为 ~/.ssh/barn_config，普通生命周期命令会自动维护。用户 SSH 配置无法安全修改时，Barn 给出需要手工加入的 Include，直接使用 barn ssh 仍可连接。

别名：sc。

barn ssh-config
barn ssh-config --install meta
barn ssh-config --install --name lab
barn ssh-config --remove --name lab

barn hosts install

barn hosts install [flags]

通过摘要匹配的提权 helper，将已应用节点的名称和别名写入宿主 /etc/hosts 的 Barn 区块。终端先展示变更并询问；非交互或结构化模式默认只预览，显式 --yes 才执行。区块内容未变化时无需提权，up 不会自动发布此文件。

Barn 1.2.0 新增 -f pigsty.yml，可在创建 VM 前发布清单节点及 all.vars.vm_hosts。每次替换整个 Barn 区块，后来不带 -f 执行会移除仅来自清单的服务名，详见本机服务名。

别名：i。

barn hosts install --json
barn hosts install --yes

barn hosts uninstall

barn hosts uninstall [flags]

只移除宿主 /etc/hosts 中 Barn 管理的区块，保留其他条目，不需要清单或部署状态。终端模式展示计划并询问；非交互或结构化模式默认预览，--yes 才执行。移除此区块不删除 VM 或修改客机 DNS 配置。

别名：u。

barn hosts uninstall --json
barn hosts uninstall --yes

实现依据

command_root.go · command_access.go · main.go

发布源码与相对 1.1.0 的变化见版本基线。

4 - 镜像命令

更新签名目录、查看和下载镜像、导入本地文件以及清理缓存。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

官方仓库和 HTTP 源必须提供受信任的分离签名。显式选择的自定义 HTTPS 仓库或本地目录可以不签名，但来源必须恰好是该仓库的 catalog.json；只要提供了签名，就必须验签成功。详见目录信任规则。

barn update

barn update [flags]

从所选仓库取得 catalog.json，并按仓库策略获取所需签名，通过信任与 revision 检查后原子激活。普通命令只使用本地元数据，不隐式刷新。本命令更新镜像元数据，不升级 Barn 可执行文件。仓库选择顺序为 --repo > --mirror > BARN_REPO > 全球官方源，详见仓库选择与信任。

barn update
barn update --mirror
barn --json update --repo /srv/barn

barn image list

barn image list [flags]

列出目录中的所有架构和已注册本地镜像，不接受镜像位置参数或架构过滤选项。读取本地活动目录，需要刷新时显式运行 barn update。barn images、barn im 都是镜像命令组的别名。

别名：ls。

barn image list
barn --json image list
barn image list --repo /srv/barn

barn image info

barn image info [image[:channel]|image@version-prefix] [flags]

查看单个镜像的元数据与已验证缓存状态，省略镜像参数时使用目录默认值。可传家族名 u24、通道 u24:stable 或数字版本前缀 el9@9，架构默认原生。--architecture/-a 是 --arch/-A 的兼容写法，不下载镜像制品。别名与精确内置版本见 Linux 镜像。

别名：in。

barn image info
barn image info u24 -A arm64
barn --json image info el9@9

barn image pull

barn image pull [image[:channel]|image@version-prefix] [flags]

下载所选制品，核验 SHA-256、字节大小、qcow2 结构和虚拟容量后激活缓存。省略镜像和架构时使用目录默认镜像与宿主原生架构，已有有效缓存可以复用。目录中的 upstream URL 记录来源，不作为下载失败时的备用地址。仍支持兼容写法 --architecture/-a；下载异架构镜像不会安装对应 QEMU 模拟器。

别名：p。

barn image pull
barn image pull u24 --mirror
barn image pull d13 -A amd64 --repo /srv/barn

barn image import

barn image import <path> [flags]

将本地普通 qcow2 文件复制到私有缓存并校验容器，可选核对预期摘要。接受相对路径、~/ 与指向普通文件的符号链接，需要 qemu-img；导入不启动镜像、不安装 cloud-init，也不修改登录凭据。

指定 local-* 名称可注册不可变的清单引用，必须同时给出启动模式与源镜像登录用户。具名导入可用 -A 记录异架构，qcow2 元数据本身无法识别 CPU 架构；无名称导入不能使用 -A。使用时设置 vm_image 及匹配的 vm_arch。详见导入与缓存规则。

别名：i。

barn image import ./base.qcow2
barn image import ./base.qcow2 --name local-dev --boot uefi --source-user ubuntu -A arm64

barn image sync

barn image sync <url|path> [flags]

从精确 URL 或本地文件激活目录，按上面的信任规则读取旁边的 .minisig 签名，适用于恢复或导入；正常刷新已配置仓库应使用 update。--repo 指定替换哪个仓库的活动元数据。无签名自定义源必须恰好是 <repo>/catalog.json，任意位置的恢复文件则需要受信任签名。

旧 revision 需要 --allow-downgrade；对于允许无签名目录的自定义仓库，从曾签名的目录切换到无签名目录也需要此选项。它不会接受无效签名，也不绕过官方仓库的签名要求和 revision 内容检查。后续回退保护仍记住历史最高 revision。

别名：sy。

barn image sync /srv/barn/catalog.json
barn image sync --repo /srv/barn /srv/recovery/catalog.json
barn image sync --allow-downgrade /srv/recovery/catalog.json

barn image reset

barn image reset [flags]

为所选仓库重新激活当前二进制内置的镜像目录，保留回退保护使用的历史最高 revision。镜像缓存与 VM 磁盘保留；需要清理缓存时使用 image prune。

barn image reset
barn --json image reset --repo /srv/barn

barn image prune

barn image prune [flags]

默认列出可回收缓存文件，--yes 才删除候选文件，与 --dry-run 互斥。所选仓库的活动目录、已应用节点的基础镜像摘要和本地别名注册表会保护所引用的文件；可识别的过期暂存文件也可清理，隔离的 .corrupt-* 文件保留。

预览和删除时应使用相同的仓库选择。删除按顺序执行，后续文件发生错误不会恢复已经删除的文件。详见清理规则。

别名：pr。

barn image prune --dry-run
barn image prune --repo /srv/barn --dry-run
barn image prune --repo /srv/barn --yes

实现依据

command_image.go · images.go

发布源码与相对 1.1.0 的变化见版本基线。

5 - 仓库命令

根据 repo.yaml 与 qcow2 制品扫描、构建和校验静态镜像仓库。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn repo scan

barn repo scan <root> [flags]

扫描包含 repo.yaml 与平铺 images/ 目录的仓库根路径，报告已跟踪、缺失、未跟踪和不安全的 qcow2 文件，不修改文件，也不需要 qemu-img。扫描成功即退出 0，即使发现问题也是如此；自动化必须检查 missing 和 unsafe，不能只看退出码。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo scan /srv/barn
barn --json repo scan /srv/barn

barn repo build

barn repo build <root> [flags]

校验 repo.yaml，通过 qemu-img 检查声明的 qcow2 制品，计算最终摘要与大小，并原子生成 catalog.json。缺失或不安全的制品导致构建失败，未跟踪文件不会收录；repo.yaml 与镜像字节保持原样。

本命令不签名或发布目录。内容变化时递增 revision，保持制品文件名不可变，并在发布前使用独立的贡献者签名工具。详见仓库格式。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo build /srv/barn
barn --json repo build /srv/barn

barn repo verify

barn repo verify <root> [flags]

根据 repo.yaml 与实际镜像字节在内存中重建预期目录，要求与已有 catalog.json 逐字节一致，需要 qemu-img。本命令检查仓库内容一致性，分离签名由目录激活流程或签名工具验证。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo verify /srv/barn
barn --json repo verify /srv/barn

实现依据

command_repo.go

发布源码与相对 1.1.0 的变化见版本基线。

6 - 宿主网络命令

检查、安装和移除 Linux 客机使用的固定 IP 网络。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn network status

barn network status [flags]

检查宿主上供 Linux 客机使用的唯一 Barn 网络，包括后端、已安装 CIDR、归属、健康状态和生命周期预检发现。--cidr 指定预期子网，省略时检查已安装子网；本操作只读。每个原生 Mac VM 的独立网络另行管理。

别名：st。

barn network status
barn --json network status --cidr 10.10.10.0/24

barn network install

barn network install [flags]

检查或安装宿主网络后端：macOS 使用 socket_vmnet，Linux 通过活动网络管理器配置 barn0。终端先展示提权计划并询问；结构化或非交互调用默认仅预览，--yes 才执行。新 Mac 建议先用 setup 获取锁定的 socket_vmnet 压缩包。

--archive、--interface-id 仅适用于 macOS，host/shared 是 macOS vmnet 模式，Linux 不接受 shared。已有网络必须匹配所选配置，变更子网或模式前先检查状态。

别名：i。

barn network install --json
barn network install --cidr 10.10.10.0/24 --yes

barn network uninstall

barn network uninstall [flags]

仅移除 Barn 管理的网络配置并恢复已记录的宿主设置，运行中 Linux 客机会阻止卸载，应先停止。终端模式显示计划后询问，结构化或非交互调用默认预览，--yes 才执行。不会删除 VM 磁盘或原生 Mac 网络。

别名：u。

barn stop
barn network uninstall --json
barn network uninstall --yes

实现依据

command_network.go

发布源码与相对 1.1.0 的变化见版本基线。

7 - macOS 命令

管理具名原生 macOS VM、桌面访问、恢复镜像与共享基础镜像。

下列选项均存在于 1.1.0 和 1.2.0。

原生 macOS VM 需要 Apple Silicon、macOS 27+ 与匹配的 Barn.app（宿主上的原生应用包），应由已登录桌面的普通用户运行。状态位于 $BARN_HOME/mac，独立于 Linux 清单。

省略可选名称时，Barn 选择唯一已有 VM 或 mac1；存在多台机器且没有 mac1 时需显式指定。configure、recreate、destroy 始终要求名称，start、stop 可以传多个名称或 --all。宿主各应用合计最多同时运行两台 macOS VM，正在安装的基础镜像也计入限制。详见机器规则、网络、输出与文件。

Mac 容量单位采用二进制，即使写作 GB 也是如此，与 Linux 清单中的十进制 GB 不同；Mac 裸容量数字表示字节。这些命令忽略 Linux 的 BARN_IMAGE/BARN_ARCH/BARN_CPU/BARN_MEM/BARN_SCALE/BARN_DISK 覆盖。

barn mac ls

barn mac ls [flags]

列出每台 VM 的状态、地址、SSH 就绪情况、macOS 版本和资源，读取本地记录并查询运行中机器，不创建、下载或启动 VM。别名为 list、status、st；直接运行 barn mac 也执行此操作。

别名：list, status, st。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac ls
barn --json mac ls

barn mac up

barn mac up [name] [flags]

创建并启动具名 VM，默认名称为 mac1，等待 SSH 和免密 sudo 可用。没有已准备基础镜像时，先确认从 Apple 下载并安装 macOS，后续机器复用基础镜像。

创建参数只用于新 VM，已有 VM 的参数不匹配会报配置冲突；修改 CPU、内存或共享目录用 configure。--no-wait 返回时首次初始化可能尚未完成，随后运行不带该选项的 mac up NAME 完成密钥和 sudo 配置。

barn mac up
barn mac up dev --cpu 8 --memory 16G --share ~/src --open
barn mac up build --yes --no-wait

barn mac start

barn mac start [name...] [flags]

启动已有 VM 并等待 SSH，不创建机器或下载镜像。可传多个名称或 --all，两者不能混用。普通启动要求机器已完成首次初始化；尚未初始化的 VM 用 up 完成，--recovery 则直接打开 macOS Recovery 桌面。

barn mac start mac1
barn mac start --all
barn mac start mac1 --recovery

barn mac stop

barn mac stop [name...] [flags]

通过 macOS 正常关闭所选机器，等待两分钟后仍未停止则断电，并在结果中报告。可传多个名称或 --all；--force 立即断电，会丢失客机中未保存的工作。磁盘和机器配置保留。

barn mac stop dev
barn mac stop --all
barn mac stop dev --force

barn mac restart

barn mac restart [name] [flags]

正常关闭一台 VM 后重新启动并应用配置，省略名称时遵循默认机器选择规则。不接受多个名称或 --all；可用 --open 打开桌面，--no-wait 跳过 SSH 等待。

barn mac restart dev
barn mac restart dev --open

barn mac configure

barn mac configure <name> [flags]

必须显式指定一台已有 VM，修改 CPU、内存、共享目录或子网时需先停止机器；剪贴板设置可以在运行时修改。磁盘和登录账户保持原样，配置在下次启动生效；当前会话的剪贴板同步可在菜单栏即时切换。省略的选项保留原设置，重复 --share 可添加或替换同名共享，--unshare 按名称移除共享。

barn mac stop dev
barn mac configure dev --cpu 8 --memory 16G --share ~/src
barn mac configure dev --unshare src --clipboard off
barn mac start dev

barn mac recreate

barn mac recreate <name> [flags]

必须显式指定机器名。擦除该 VM 磁盘，使用原名称、账户、资源、共享目录和地址重新克隆 macOS，客机文件、应用和设置全部丢失。终端要求输入 recreate，脚本需 --yes 或 --force，没有 -y。--update 使用最新已准备基础镜像，应先执行 mac image update。

barn mac recreate dev
barn mac image update --yes
barn mac recreate dev --update --yes

barn mac destroy

barn mac destroy <name...> [flags]

必须显式指定一个或多个机器名，将机器断电并删除磁盘、密钥、密码和设置，保留共享基础镜像和其他机器。终端要求输入 destroy，脚本需 --yes 或 --force，没有 -y。宿主共享目录不会删除；未使用基础镜像用 mac image prune 清理。

barn mac destroy dev
barn mac destroy mac1 mac2 --yes

barn mac open

barn mac open [name] [flags]

显示 VM 的桌面窗口，机器已停止时会先启动。关闭窗口后 VM 继续在后台运行，剪贴板在窗口聚焦时共享。尚未完成首次初始化且已运行的 VM 可直接打开桌面；未运行时用 mac up NAME --open 继续首次启动。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac open
barn mac open dev

barn mac ssh

barn mac ssh [flags] [name] [-- command...]

使用该 VM 专属 SSH 私钥与固定的宿主密钥连接，省略远程命令时打开交互 shell。-- 前最多传一个已有机器名及 Barn 选项；远程命令必须放在 -- 后，按普通 SSH 方式拼接后交给远程 shell。远程退出码原样返回。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac ssh dev
barn mac ssh dev -- 'sw_vers; id'

barn mac exec

barn mac exec [flags] [name] -- command...

使用 VM 专属 SSH 连接运行远程程序，必须提供 -- 和非空首参数；分开的参数保留边界及后续空值，shell 表达式请显式使用 sh -c。也兼容单个命令字符串。Barn 选项置于 -- 前，远程退出码原样返回，结构化结果包含 stdout、stderr 和 exit_code。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac exec dev -- sw_vers
barn mac exec dev -- printf '<%s>\n' 'a b' ''
barn --json mac exec dev -- sh -c 'echo out; exit 3'

barn mac password

barn mac password [name] [flags]

读取客机登录账户的密码，用于桌面解锁及管理员询问。默认输出密码，--copy 改为复制到宿主剪贴板。密码文件与机器 SSH 私钥采用相同保护；注意选择输出位置。

barn mac password dev
barn mac password dev --copy

barn mac ssh-config

barn mac ssh-config [flags]

打印全部 Mac VM 的 OpenSSH 配置片段，支持 ssh、scp、rsync 和编辑器按名称连接，每台机器使用独立私钥与固定宿主密钥。首台 VM 就绪时自动安装，生命周期命令持续更新。--remove 移除配置并保持停用，直到显式 --install；两选项互斥，也不接受机器选择器。已有 SSH 别名冲突时仅发布 IP 地址条目。

barn mac ssh-config
barn mac ssh-config --install
barn mac ssh-config --remove

barn mac logs

barn mac logs [name] [flags]

读取 VM 的 runner.log 尾部，包含启动、网络、关闭和 Apple Virtualization 错误。--lines/-n 为正整数，默认 100；这里的 -n 表示行数，不是跳过等待。没有跟随选项。

barn mac logs dev
barn mac logs dev --lines 200

barn mac setup

barn mac setup [flags]

提前准备共享 macOS 基础镜像：确认后从 Apple 下载 IPSW，或读取 --ipsw 指定的本地恢复文件，再安装为未启动的基础镜像。后续 VM 从它克隆。此命令不创建具名机器；直接 mac up 也会在需要时自动执行此准备。

barn mac setup --yes
barn mac setup --ipsw ~/Downloads/restore.ipsw --disk 200G

barn mac image ls

barn mac image ls [flags]

列出缓存的 IPSW 恢复文件和已准备基础镜像，包括状态、占用空间及使用它们的 VM；别名为 list。这是本地状态查询，无需调用原生运行器。

别名：list。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac image ls
barn --json mac image ls

barn mac image update

barn mac image update [flags]

从 Apple 查询最新 macOS 27 恢复镜像，经确认后下载并安装为新机器的默认基础镜像；也可通过 --ipsw 指定本地文件。已有 VM 继续使用原基础镜像，显式 mac recreate NAME --update 才替换该 VM 磁盘。

barn mac image update --yes
barn mac image ls

barn mac image prune

barn mac image prune [flags]

默认列出没有机器使用、且不是当前默认基础镜像的清理候选，只有传 --yes 才删除。--installers 同时纳入下载的 IPSW 与未完成下载。VM 的引用关系会保护仍在使用的基础镜像。

barn mac image prune
barn mac image prune --installers --yes

barn mac doctor

barn mac doctor [flags]

只读检查宿主 macOS 与 Apple Silicon 支持、Mac 组件签名、可用磁盘空间、基础镜像以及每台 VM 的文件、密钥、共享目录、网络和 SSH，不修改或启动机器。Linux/QEMU 环境用顶层 barn doctor 检查。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac doctor
barn --json mac doctor

实现依据

command_mac.go

发布源码与相对 1.1.0 的变化见版本基线。