Command Reference on Barn

macOS Commands

Wed, 11 Nov 2026 00:00:00 +0800

Manage named native macOS VMs, desktop access, restore images, and shared bases.

All options below are present in 1.1.0 and the reviewed development tree.

Native macOS VMs require Apple Silicon, macOS 27+, and the matching Barn.app native app bundle, invoked as the logged-in desktop user. Their state lives under $BARN_HOME/mac and is independent of the Linux inventory.

For an optional name, Barn selects the sole existing VM or mac1; multiple VMs without mac1 require an explicit name. configure, recreate, and destroy always require names. start and stop accept multiple names or --all. At most two macOS VMs can run concurrently across apps on the host, including an active base installation. See machine rules, networking, output, and files.

Host Network Commands

Wed, 11 Nov 2026 00:00:00 +0800

Inspect, install, and remove the fixed-IP network used by Linux guests.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

`barn network status`

barn network status [flags]

Inspect the one host-wide Linux-guest network: backend, installed CIDR, ownership, health, and lifecycle preflight findings. --cidr checks an expected subnet; omitting it inspects the installed one. It is read-only. This network is separate from each native Mac VM’s private network.

Repository Commands

Wed, 11 Nov 2026 00:00:00 +0800

Scan, build, and verify static image repositories from repo.yaml and qcow2 artifacts.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

`barn repo scan`

barn repo scan <root> [flags]

Scan one repository root containing repo.yaml and a flat images/ directory. Report tracked, missing, untracked, and unsafe qcow2 files without changing them or requiring qemu-img. Successful scanning exits 0 even with findings; automation must inspect missing and unsafe rather than rely on the exit code alone.

Image Commands

Wed, 11 Nov 2026 00:00:00 +0800

Refresh signed catalogs, inspect or download images, import local files, and prune caches.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

Official repositories and HTTP sources require a trusted detached signature. An explicitly selected custom HTTPS repository or local directory can be unsigned, provided the source is exactly that repository’s catalog.json. Any supplied signature must verify. See catalog trust.

Guest Access and Hosts

Wed, 11 Nov 2026 00:00:00 +0800

Connect to Linux guests, run scripts, read logs, and publish SSH or hosts entries.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

`barn ssh`

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

Open an interactive SSH session on the selected prepared node, defaulting to the prepared control node (or first prepared node). Remote commands require --; arguments after it are joined for the remote shell like ordinary ssh. Put Barn options before the separator. Node selectors are resolved node names, not IP addresses, aliases, or groups.

Linux Lifecycle

Wed, 11 Nov 2026 00:00:00 +0800

Plan, create, start, resize, inspect, and explicitly remove Linux virtual machines.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

Node arguments are resolved names such as meta and node-1. Omit them to select all nodes in the command’s inventory/applied scope. IP addresses, groups, and vm_alias are not selectors. plan, up, reload, resize, and recreate read -f, then the current directory’s inventory, then applied state. Other lifecycle commands use applied state directly.

Preparation and Utilities

Wed, 11 Nov 2026 00:00:00 +0800

Initialize inventories, prepare the host, validate configuration, and inspect the CLI.

This reference covers Barn 1.2.0. Option tables distinguish options also available in 1.1.0 from additions in 1.2.0; see the version baseline. All commands inherit the global options.

`barn setup`

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

Prepare host packages, the fixed-IP network, images, and the selected inventory. It does not create the Linux VMs: run barn up afterward. With no template or -f, reuse the discovered inventory or generate meta. The templates meta, dual, trio, and full contain 1, 2, 3, and 4 nodes. -c and specification flags customize a generated template; explicit specification flags cannot be used to rewrite an existing inventory. In 1.2.0, specification environment variables are also ignored when setup reuses an inventory.