Command Reference

Every Barn command with syntax, all local options, defaults, examples, and version availability.

3 minute read

Find a command below for its arguments, complete local option table, examples, and effects. This reference follows the command-index and command-family organization of PIG. Barn’s CLI contracts describe structured output and exit codes; Configuration defines inventory fields.

Version baseline

This reference covers Barn 1.2.0, released on 2026-11-12 from 90f6158. Its 57 operation commands and 174 local option entries were checked against the CLI help output in both languages.

Label	Availability	Behavior
1.1.0	Options available in both 1.1.0 and 1.2.0	1.1.0 used 2 vCPUs / 4 GiB by default and accepted CPU/memory resize through the inventory
1.2.0	Added in 1.2.0	Resource flags and environment overrides, `vm_scale`, root-disk growth, lifecycle `--parallel`, `vm_hosts`, and `hosts install -f`; defaults are now 1 vCPU / 2 GiB

To preserve the previous defaults when upgrading, set vm_cpu: 2 and vm_mem: 4GiB explicitly and inspect barn plan. Existing applied VMs keep their resources until a resource-changing operation is requested. Use barn version and barn COMMAND --help to check an installed build. See the release notes and release validation.

Command index

Task	Commands and detailed reference
Prepare	setup, init, validate, doctor
Plan and create	plan, up
Start and stop	start, stop, restart, reload
Change and inspect	resize, recreate, status
Delete	destroy, purge
Access Linux guests	ssh, exec, logs, provision, ssh-config
Publish host names	hosts install, hosts uninstall
Refresh catalog	update, image sync, image reset
Manage Linux images	image list, info, pull, import, prune
Maintain a repository	repo scan, build, verify
Host network	network status, install, uninstall
Native macOS VMs	mac ls, up, start, stop, restart, configure, recreate, destroy
Mac access	mac open, ssh, exec, password, ssh-config, logs
Mac preparation	mac setup, doctor, image ls, image update, image prune
CLI utilities	version, completion, help

Global options

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

Option	Meaning
`-h`, `--help`	Human-readable help for the selected command; exits `0`
`--json`	Structured JSON on stdout; progress and diagnostics stay on stderr
`--yaml`	Structured YAML on stdout; mutually exclusive with `--json`
`-v`, `--verbose`	Bounded diagnostics on stderr
`--version`	Root-command shortcut to display build identity; use `barn version --json` for a structured report

Global output options can appear before or after a subcommand, but must precede the remote-command -- separator used by ssh and exec. -f, -I, -A, -p, and --yes are local options: consult the selected command’s table. -f means follow for logs; -n means line count for mac logs. Long boolean options accept =true or =false.

BARN_OUTPUT and BARN_VERBOSE set presentation defaults. BARN_HOME selects private state (default ~/.barn); use an absolute path when changing directories. Linux and Mac machines share that data root but have independent lifecycles. See environment variables and exit codes.

barn and help

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

With no arguments, text mode prints complete help and exits 0; JSON/YAML mode returns suggested actions[]. Explicit help always prints human-readable text. Groups image, repo, network, hosts, and mac image require a subcommand and exit 2 without one. The mac group is the exception: it defaults to mac ls. It is hidden from root help on Linux and Intel Macs, while explicit Mac help remains available.

Short aliases are scoped to their parent. barn im ls is barn image list; barn mac st is barn mac ls. The per-command pages list each alias. There is no rm alias for purge.