Preparation and Utilities

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

6 minute read

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.

--dry-run previews the transaction. Applying it requires terminal confirmation or --yes; operating-system privilege prompts can still occur. On a fresh unedited default template, setup may choose a free private /24 and save barn.yml.before-network-change if the default subnet conflicts. Explicit inventories retain their subnet. On Linux, foreign-architecture QEMU emulators and firmware need separate installation.

Aliases: s.

Option	Meaning / default	Available in
`-A, --arch string`	override deployment vm_arch: native, amd64, or arm64; environment overrides require 1.2.0	1.1.0
`-c, --cidr string`	generated template network as a canonical RFC1918 IPv4 /24	1.1.0
`-C, --cpu string`	Base vCPUs before scale, integer 1–256; effective CPU count is also limited to 256; overrides BARN_CPU	1.2.0
`-D, --disk string`	Absolute root capacity, at least the base virtual size; bare integer means GiB; overrides BARN_DISK	1.2.0
`-d, --dry-run`	show the resolved setup plan without changing anything	1.1.0
`-f, --file string`	Inventory to prepare; mutually exclusive with a template argument	1.1.0
`-I, --image string`	override vm_image/vm_version for selected nodes; environment overrides require 1.2.0	1.1.0
`-M, --mem string`	Base memory before scale, minimum 512 MiB; bare integer means MiB; overrides BARN_MEM	1.2.0
`--mirror`	use the China official repository at repo.pigsty.cc; overridden by `--repo`	1.1.0
`-m, --mode string`	macOS fixed-IP network backend: host or shared (default “host”)	1.1.0
`-r, --repo string`	image repository URL or local directory, also used for socket_vmnet; overrides `--mirror` and $BARN_REPO	1.1.0
`-S, --scale string`	Integer 1–256 multiplying base CPU and memory only; disk does not scale; overrides BARN_SCALE	1.2.0
`-y, --yes`	accept the one-time setup plan (required without a terminal)	1.1.0

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]

Generate a Pigsty-compatible YAML inventory. The default is the one-node meta template in ./barn.yml; dual, trio, and full add nodes at .11, .12, and .13. The control node is .10. Existing files require --force; -o - prints the inventory. This command does not download images or prepare the host.

Stable 1.1.0 defaults to 2 vCPUs and 4 GiB per node; 1.2.0 defaults to 1 vCPU and 2 GiB. Both use a 64 GiB root and a separate 128 GiB /data disk. The 1.2.0 templates persist all six specification fields, including vm_scale. See specification defaults.

Option	Meaning / default	Available in
`-A, --arch string`	override deployment vm_arch: native, amd64, or arm64; environment overrides require 1.2.0	1.1.0
`-c, --cidr string`	rebase the generated template to a canonical RFC1918 IPv4 /24	1.1.0
`-C, --cpu string`	Base vCPUs before scale, integer 1–256; effective CPU count is also limited to 256; overrides BARN_CPU	1.2.0
`-D, --disk string`	Absolute root capacity, at least the base virtual size; bare integer means GiB; overrides BARN_DISK	1.2.0
`--force`	Overwrite the destination inventory; default preserves existing files	1.1.0
`-I, --image string`	override vm_image/vm_version for selected nodes; environment overrides require 1.2.0	1.1.0
`-M, --mem string`	Base memory before scale, minimum 512 MiB; bare integer means MiB; overrides BARN_MEM	1.2.0
`-o, --output string`	write to this path instead of ./barn.yml; ‘-’ writes to stdout	1.1.0
`-S, --scale string`	Integer 1–256 multiplying base CPU and memory only; disk does not scale; overrides BARN_SCALE	1.2.0

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]

Read one inventory, validate the fields Barn consumes, and report the resolved nodes. It accepts no node selectors. Discovery checks barn.yml, barn.yaml, pigsty.yml, then pigsty.yaml in the current directory; no inventory means an error even if applied state exists. Overrides affect this validation only. Use --json to inspect the resolved specification, and plan to compare it with an existing deployment.

Aliases: v.

Option	Meaning / default	Available in
`-A, --arch string`	override deployment vm_arch: native, amd64, or arm64; environment overrides require 1.2.0	1.1.0
`-C, --cpu string`	Base vCPUs before scale, integer 1–256; effective CPU count is also limited to 256; overrides BARN_CPU	1.2.0
`-D, --disk string`	Absolute root capacity, at least the base virtual size; bare integer means GiB; overrides BARN_DISK	1.2.0
`-f, --file string`	Inventory to validate; otherwise use local discovery, with no applied-state fallback	1.1.0
`-I, --image string`	override vm_image/vm_version for selected nodes; environment overrides require 1.2.0	1.1.0
`-M, --mem string`	Base memory before scale, minimum 512 MiB; bare integer means MiB; overrides BARN_MEM	1.2.0
`-r, --repo string`	image repository whose catalog checks the images; overrides $BARN_REPO	1.1.0
`-S, --scale string`	Integer 1–256 multiplying base CPU and memory only; disk does not scale; overrides BARN_SCALE	1.2.0

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

`barn doctor`

barn doctor [flags]

Probe QEMU, native acceleration, firmware, OpenSSH, a short accelerated boot test, and host networking. This is a host diagnostic and takes no inventory or node arguments. Missing compute capabilities fail the command; missing network setup is reported as informational. Inspect barn network status for the detailed network plan and barn mac doctor for native macOS VMs.

Aliases: dt.

No local options beyond --help; global presentation options still apply.

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

`barn version`

barn version [flags]

Print version, source commit, build time, host OS, and architecture. Development builds normally report dev; release identity comes from the build stamp. Use this report when matching documentation or filing an issue. The root shortcut barn --version is also available.

Aliases: ver.

No local options beyond --help; global presentation options still apply.

barn version
barn --json version

`barn completion`

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

Require one shell name: bash, zsh, fish, or powershell. Print its completion script to stdout; the command does not install the script. Completion includes scoped flags, templates, image aliases, and best-effort node names. Reload it after upgrading Barn. Use text output when sourcing shell code.

No local options beyond --help; global presentation options still apply.

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

Implementation

command_setup.go · command_misc.go · command_root.go

The version baseline identifies the released source and the changes since 1.1.0.