Command Reference

• 1: Preparation and Utilities
• 2: Linux Lifecycle
• 3: Guest Access and Hosts
• 4: Image Commands
• 5: Repository Commands
• 6: Host Network Commands
• 7: macOS Commands

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

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

1 - Preparation and Utilities

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.

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.

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.

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.

2 - Linux Lifecycle

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.

Specification overrides, scaling, and their environment variables are defined in Configuration. The 1.2.0 concurrency option applies only where --parallel is listed; plan, resize, and status do not accept it. For structured results and exit codes, see CLI contracts.

barn plan

barn plan [node...] [flags]

Compare the effective desired inventory with applied state without changing VMs or downloading images. Report exact images, resources, per-disk actions, and nodes needing creation, resize, recreation, start, or explicit removal. Catalog images need only local metadata; inspecting a named local image also needs qemu-img.

Exit 0 means the plan was produced, including plans blocked by omitted nodes. Automation must inspect action, blocked, and the change arrays. Explicit selectors retain the applied definitions of unselected peers. Planning output describes the result.

Aliases: pl.

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

barn up

barn up [node...] [flags]

Create missing nodes, start stopped nodes, and retry unfinished guest setup while keeping healthy running VMs alive. It waits for management SSH unless --no-wait is set, and refreshes host SSH aliases and guest host/control-node entries. Non-fatal guest setup problems appear in warnings; ready nodes still succeed.

On an interactive first run, it can prepare missing host dependencies and generate meta when no inventory or applied deployment exists. Scripts should run setup --yes first. Existing definition changes require resize or recreate; inventory omissions require explicit destroy. --rollback only removes safe, uncommitted artifacts from preparation failures in this run.

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

barn start

barn start [node...] [flags]

Start selected stopped nodes from applied state and wait for SSH. It works from any directory using the same BARN_HOME, without reading an inventory or creating nodes. It refreshes SSH access; use up to retry unfinished guest setup on an already-running VM. An unavailable share fails its node while independent nodes continue.

barn start
barn start meta --no-wait

barn stop

barn stop [node...] [flags]

Stop selected running Linux VMs using their recorded process identities. It retains root disks, data disks, keys, and deployment state. With no names, stop the whole Linux deployment; it does not stop named macOS VMs or remove the host network.

barn stop meta
barn stop

barn restart

barn restart [node...] [flags]

Stop and start existing nodes using applied state. Inventory edits are not read. Use reload to re-read an inventory, or resize/recreate to apply changed definitions. It waits for SSH unless --no-wait is set.

barn restart
barn restart meta --no-wait

barn reload

barn reload [node...] [flags]

Validate the desired specification and startup dependencies before stopping selected nodes, then converge them through up. It can create newly added nodes. Changes requiring resize or recreation, and omitted applied nodes, fail preflight before any VM stops. Use restart when you want only the recorded configuration.

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

barn resize

barn resize [node...] [flags]

Apply CPU and memory changes while preserving VM identity, disks, and SSH keys. Supported increases use hotplug; decreases or unsupported live changes use a stop/start fallback. Stable 1.1.0 reads CPU/memory changes from the inventory. Image, architecture, data-disk, network, share, create, and remove changes cannot be applied by resize.

Barn 1.2.0 additionally accepts resource flags and grows the existing root with -D 128GiB. Root growth stops QEMU, expands its image, boots the guest to grow and verify a last plain ext4/XFS root partition, then restores an initially stopped VM to stopped. Targets must grow and align to 512 bytes. Retry an interrupted growth with the same target; shrinking, LVM, encrypted roots, and non-last partitions are unsupported. See root growth and recovery. CLI overrides do not rewrite the inventory.

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

barn recreate

barn recreate [node...] [flags]

Replace the selected VMs from the desired inventory. This deletes their root disks and non-persistent data disks; compatible persistent data disks are reattached. Inspect plan first. A terminal asks you to type recreate; scripts require --yes or --force (no -y).

No selector means the whole inventory. If it omits an applied node, the operation fails before stopping VMs; explicitly destroy that node or restore it in the inventory. Selected recreation preserves unselected peers. A successful recreation also refreshes SSH access.

Aliases: rc.

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

barn status

barn status [node...] [flags]

Inspect recorded node configuration and live QEMU process identity without requiring the inventory directory. running reports a verified VM process, not an SSH readiness probe. --verbose adds runtime details; --json exposes node records, active-operation notes, and failures. A degraded node can produce exit 5 while healthy peers are still listed. The 1.2.0 text output uses compact SPEC values such as 2c4g.

Aliases: st.

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

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

barn destroy

barn destroy [node...] [flags]

Delete selected VMs, or the whole deployment without selectors. Root and non-persistent data disks are deleted; persistent data disks are retained unless a whole-deployment deletion flag is explicit. Terminal confirmation requires typing destroy; scripts need --yes or --force, with no -y.

--delete-persistent and --purge require whole-deployment scope. --purge also removes deployment keys and state. The image cache, host network, and native Mac VMs remain. Removing the control node promotes the first remaining node; update admin_ip and run up to configure its control SSH access.

Aliases: de.

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

barn purge

barn purge [flags]

Immediately delete the entire Linux deployment, including root disks, persistent data disks, keys, state, and the default SSH fragment. It takes no node names and reads no inventory. It has no --yes, -y, or --force: use --ask when you want to review the scope and confirm with y/yes (Enter cancels).

Cached images, host networking, and Mac VMs remain. An absent deployment is an idempotent success; ambiguous retained artifacts still require identity checks. The 1.2.0 --parallel flag controls node work during disposal.

barn purge --ask
barn --json purge

Implementation

command_lifecycle.go · main.go

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

3 - Guest Access and Hosts

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.

A remote command returns its exit status unchanged. Structured interactive SSH sends session output to stderr and the final report to stdout. See SSH argument rules.

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

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

barn exec

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

Run one remote command on the selected prepared node, with the same default-node selection as ssh. -- and a non-empty first command argument are required. Separate arguments preserve spaces, quotes, and later empty values. Use sh -c for pipelines, redirection, or variable expansion; a single command string is also accepted as compatibility shell shorthand.

Text mode forwards the child output and exit status. Structured output includes success, exit_code, stdout, and stderr. A nonzero remote exit is passed through, so inspect that result before interpreting the number as a Barn error class.

Aliases: ex.

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

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]

Read the selected node’s serial console or QEMU diagnostic log, defaulting to the prepared control/first node. --source events selects the deployment-wide bounded event log and takes no node argument; it can be read before deployment state exists. Following logs emits a stream rather than one final document. -f means follow here, not inventory. QEMU argv is hidden unless verbose output is enabled.

Aliases: 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]

Stream a local Bash script over the verified deployment SSH connection to selected running nodes, or all nodes if no names are supplied. The script is not left behind as a guest file; its digest is recorded for auditing. It does not create or start VMs.

--script is required. The default concurrency is 1 and the timeout is one hour for the operation. Unlike development lifecycle concurrency, --parallel 0 is invalid. --sudo uses noninteractive guest sudo -n; ensure the guest user has the required permission. Review per-node output and failures in structured mode.

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

barn ssh-config

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

Print the Linux deployment’s OpenSSH fragment. --install writes a fragment and one Include in ~/.ssh/config; printing and installation accept node selectors. --remove removes only the named Barn fragment, needs no deployment state, and takes no nodes. Install and remove are mutually exclusive.

The default prefix is barn and its fragment is ~/.ssh/barn_config. Normal lifecycle commands maintain the default fragment automatically. If the user’s SSH configuration cannot be safely edited, Barn reports the manual Include instruction; direct barn ssh remains usable.

Aliases: 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]

Publish applied node names and aliases in the Barn-owned block of the host’s /etc/hosts, using the digest-matched privileged helper. On a terminal it shows the change and asks before applying; in noninteractive or structured mode it only previews unless --yes is passed. An unchanged block requires no privilege. This file is not automatically published by up.

Barn 1.2.0 adds -f pigsty.yml, publishing inventory nodes plus all.vars.vm_hosts before VM creation. It replaces the whole Barn block, so a later call without -f drops inventory-only service names. See local service names.

Aliases: i.

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

barn hosts uninstall

barn hosts uninstall [flags]

Remove only the Barn-owned /etc/hosts block while retaining other entries. It needs no inventory or deployment state. Terminal mode displays a plan and asks; noninteractive/structured mode previews unless --yes is supplied. Removing the block does not delete VMs or change guest DNS configuration.

Aliases: u.

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

Implementation

command_root.go · command_access.go · main.go

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

4 - Image Commands

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.

barn update

barn update [flags]

Fetch catalog.json and its signature when required by repository policy, verify trust and revision rules, then atomically activate the catalog. Ordinary commands use local metadata and never update it implicitly. This updates image metadata, not the Barn executable. Repository precedence is --repo > --mirror > BARN_REPO > the global official repository. See repository selection and trust.

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

barn image list

barn image list [flags]

List every catalog architecture and registered local image. It has no image selector or architecture filter. The active local catalog is used; run barn update explicitly to refresh it. Aliases barn images and barn im select the same image command group.

Aliases: 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]

Inspect metadata and verified cache state for one image, using the catalog default if omitted. Select a family (u24), channel (u24:stable), or numeric version prefix (el9@9). Architecture defaults to native. The compatibility spelling --architecture/-a is also accepted for --arch/-A. It does not download the artifact. Supported aliases and exact embedded versions are in Linux images.

Aliases: 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]

Download the selected artifact and verify its SHA-256, byte size, qcow2 structure, and virtual capacity before activating the cache entry. Omitted image and architecture select the catalog default and native host architecture. Existing valid cached bytes are reused. The catalog’s upstream URL is provenance, not a download fallback. --architecture/-a remains a compatibility alias. A foreign artifact does not install the corresponding QEMU emulator.

Aliases: 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]

Copy a local regular qcow2 image into the private cache and validate its container, optionally against an expected digest. Relative paths, ~/, and symlinks to regular files are accepted. qemu-img is required; importing does not boot the image, add cloud-init, or change credentials.

A local-* name registers an immutable inventory reference and requires boot mode plus the source login user. Named imports can record a foreign architecture with -A; qcow2 metadata does not identify CPU architecture, and unnamed imports cannot use -A. Set both vm_image and a matching vm_arch when using it. See import and cache rules.

Aliases: 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]

Activate a catalog from one exact URL or local file, reading its adjacent .minisig signature under the trust policy above. This is the recovery/import path; use update for the configured repository’s normal endpoint. --repo chooses which repository’s active metadata to replace. An unsigned custom source must be exactly <repo>/catalog.json; an arbitrary recovery file requires a trusted signature.

Older revisions require --allow-downgrade. For custom repositories that allow unsigned catalogs, switching from a previously signed catalog to an unsigned one also requires this flag. It never permits an invalid signature or bypasses the official-repository signature requirement and revision-content checks. Future downgrade protection still remembers the highest revision.

Aliases: 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]

Reactivate the catalog embedded in the current binary for the selected repository. It keeps the highest accepted revision used by downgrade protection. Cached images and VM disks are retained; this is not a cache deletion command.

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

barn image prune

barn image prune [flags]

List reclaimable cache files by default. --yes deletes candidates; it is mutually exclusive with --dry-run. The selected active catalog, applied node base-image digests, and registered local aliases protect their referenced files. Stale recognized staging files can also be removed; quarantined .corrupt-* files remain.

Preview with the same repository selection you will use for deletion. Deletion is sequential; an error on a later file does not restore files already removed. See pruning rules.

Aliases: pr.

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

Implementation

command_image.go · images.go

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

5 - Repository Commands

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.

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

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

barn repo build

barn repo build <root> [flags]

Validate repo.yaml, inspect the declared qcow2 artifacts with qemu-img, calculate final digests/sizes, and atomically generate catalog.json. Missing or unsafe artifacts fail the build; untracked files are omitted. repo.yaml and image bytes are preserved.

This command does not sign or publish a catalog. Increment the revision for changed contents, keep artifact filenames immutable, and use the separate contributor signing tools before publication. See repository format.

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

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

barn repo verify

barn repo verify <root> [flags]

Rebuild the expected catalog in memory and require byte-for-byte agreement with the existing catalog.json, using repo.yaml and actual image bytes. Requires qemu-img. It checks repository consistency; detached-signature verification belongs to catalog activation and the signing tools.

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

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

Implementation

command_repo.go

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

6 - Host Network Commands

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.

Aliases: st.

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

barn network install

barn network install [flags]

Inspect or install the host-wide backend: socket_vmnet on macOS or barn0 through the active Linux network manager. On a terminal it shows a privileged plan and asks; structured/noninteractive calls only preview unless --yes is supplied. On a fresh Mac, use setup to obtain the pinned socket_vmnet archive first.

--archive and --interface-id are macOS-only. host/shared are macOS vmnet modes; Linux rejects shared. An existing network must match the chosen configuration; review status before changing subnet or mode.

Aliases: i.

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

barn network uninstall

barn network uninstall [flags]

Remove only Barn-owned network configuration and restore recorded host settings. Stop running Linux guests first: the operation refuses a live deployment. Terminal mode asks after showing the plan; structured/noninteractive calls preview unless --yes is set. This does not delete VM disks or native Mac networks.

Aliases: u.

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

Implementation

command_network.go

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

7 - macOS Commands

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.

Mac resource sizes use binary units even for GB, unlike Linux inventory decimal GB; a bare Mac size is bytes. These commands ignore Linux BARN_IMAGE/BARN_ARCH/BARN_CPU/BARN_MEM/BARN_SCALE/BARN_DISK overrides.

barn mac ls

barn mac ls [flags]

Show every machine: its state, address, SSH readiness, macOS version and resources. It reads local records and asks each running machine, and never creates, downloads or starts anything.

Running barn mac without a subcommand also lists machines.

Aliases: list, status, st.

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

barn mac ls
barn --json mac ls

barn mac up

barn mac up [name] [flags]

Create the named machine (mac1 by default), start it, and wait until SSH and passwordless sudo work. Without a prepared macOS base, up first downloads the restore image from Apple after confirmation and installs it once; later machines clone that base.

Creation options apply to a new machine. For an existing machine, up starts it and rejects options that differ from its configuration; use configure for supported setting changes.

--no-wait returns once the VM is running. First-boot provisioning may still be in progress; run barn mac up NAME again to wait for SSH and finish initialization.

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]

Start existing machines and wait for SSH without creating machines or downloading images. --recovery boots macOS Recovery with its desktop shown.

Select names or --all, not both. Ordinary start requires completed first-boot initialization; use up to finish an uninitialized VM.

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

barn mac stop

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

Shut machines down normally through macOS. A machine that has not stopped after two minutes is powered off, and the result says so. --force powers off at once, like holding a power button; unsaved work in the guest is lost.

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

barn mac restart

barn mac restart [name] [flags]

Shut a machine down normally and start it again, applying configuration changes.

Accepts at most one name; there is no --all. Omitted names follow the default-machine rule above.

barn mac restart dev
barn mac restart dev --open

barn mac configure

barn mac configure <name> [flags]

Change settings of an existing machine without touching its disk or account. CPUs, memory, shared folders and the network change while the machine is stopped; the clipboard setting can change anytime. Saved configuration, including clipboard changes, applies at the next start; use the menu-bar control to toggle clipboard sharing in the current session.

An explicit name is required. Omitted flags retain their values. --share adds or replaces a named share; --unshare removes one.

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]

Erase the machine’s disk and start a fresh macOS with the same name, account, resources, shared folders and address. --update uses the newest prepared base (see barn mac image update). Its files, apps and settings are lost.

A terminal asks you to type recreate; scripts require --yes or --force, with no -y shorthand.

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

barn mac destroy

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

Power machines off and delete them: disk, keys, password and settings. The shared macOS base and other machines are kept; barn mac image prune removes unused bases.

Explicit names are required. A terminal asks you to type destroy; scripts require --yes or --force, with no -y. Shared host folders are retained.

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

barn mac open

barn mac open [name] [flags]

Show the machine’s desktop window, starting the machine first when it is stopped. Closing the window keeps the machine running in the background; the clipboard is shared while the window is focused.

An uninitialized running VM can be viewed here; for a stopped uninitialized VM use mac up NAME --open.

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

barn mac open
barn mac open dev

barn mac ssh

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

Connect with the machine’s own key and pinned host key. Everything before – must be empty or one known machine name, apart from Barn flags. A remote command requires –, and its first argument must not be empty. For exec, pass the program and its arguments separately to preserve argument boundaries, including later empty values. Use sh -c explicitly for shell expressions. A single command string remains supported as shell shorthand for compatibility. exec requires a command. ssh passes the command line to the remote shell like plain ssh. Without a command, ssh opens an interactive session.

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

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

barn mac exec

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

Connect with the machine’s own key and pinned host key. Everything before – must be empty or one known machine name, apart from Barn flags. A remote command requires –, and its first argument must not be empty. For exec, pass the program and its arguments separately to preserve argument boundaries, including later empty values. Use sh -c explicitly for shell expressions. A single command string remains supported as shell shorthand for compatibility. exec requires a command. ssh passes the command line to the remote shell like plain ssh. Without a command, ssh opens an interactive session.

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

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]

Show the password of the machine’s login account, needed for the lock screen and administrator prompts in its desktop. It is stored next to the machine’s SSH key with the same protection. --copy puts it on the clipboard instead of printing it.

barn mac password dev
barn mac password dev --copy

barn mac ssh-config

barn mac ssh-config [flags]

Print the OpenSSH fragment that lets ssh, scp, rsync and editors reach each machine by name with its own key and pinned host key. The first machine to become ready installs it as one Include in ~/.ssh/config, and lifecycle commands keep it current. –remove deletes only what Barn installed and keeps it out until –install. A name that ~/.ssh/config already uses for another host is published by address only.

--install and --remove are mutually exclusive. This command takes no machine selectors.

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

barn mac logs

barn mac logs [name] [flags]

Show the last lines of the machine’s runtime log: startup, network, shutdown and Apple Virtualization errors.

--lines/-n must be positive and defaults to 100. There is no follow flag; -n means lines, not no-wait.

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

barn mac setup

barn mac setup [flags]

Download macOS from Apple after you confirm, or read –ipsw, and install it once into the unbooted base that every machine is cloned from. up does this automatically; setup lets you do it ahead of time.

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

barn mac image ls

barn mac image ls [flags]

List restore images and bases with their state, disk usage and the machines that use them.

This local-state query does not invoke the native runner.

Aliases: list.

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

barn mac image ls
barn --json mac image ls

barn mac image update

barn mac image update [flags]

Ask Apple for the newest macOS 27 restore image, download it after you confirm, and install it as the default base for new machines. Existing machines keep their base until barn mac recreate –update.

barn mac image update --yes
barn mac image ls

barn mac image prune

barn mac image prune [flags]

List unused bases except the current default base. --installers also includes downloaded restore images and partial downloads. Deletion requires --yes.

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

barn mac doctor

barn mac doctor [flags]

Check macOS and Apple Silicon support, the Mac component’s signature, free disk space, the prepared base, and every machine: its files, keys, shared folders, network and SSH. It changes nothing and starts nothing.

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

barn mac doctor
barn --json mac doctor

Implementation

command_mac.go

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