CLI Guide

Shell completion

Generate completion for the shell in use:

holos completion bash > ~/.local/share/bash-completion/completions/holos
holos completion zsh > ~/.zfunc/_holos
holos completion fish > ~/.config/fish/completions/holos.fish

The scripts complete top-level commands and subcommands for snapshots, volumes, and completion.

Image locks

Run holos images lock -f holos.yaml to write a project image lockfile. Use holos up --locked in CI or deployment scripts to require the adjacent lockfile and reject changed image bytes or service entries. If you generated a custom lockfile with images lock -o, pass the same path to up --lockfile.

Capacity preflight

holos validate --capacity checks aggregate replica CPU and memory requests against the current host and the process’s cgroup limits before launch. --network checks that configured bridge/tap networks refer to bridges that already exist. Both checks are optional; use them in deployment scripts when host overcommit or missing host network setup is not desired.

Ad Hoc VMs

holos run launches a one-off VM without a compose file:

holos run ubuntu:noble
holos run --vcpu 4 --memory 4G ubuntu:noble
holos run -p 8080:80 --pkg nginx \
  --runcmd 'systemctl enable --now nginx' alpine
holos run -v ./code:/srv:ro ubuntu:noble
holos run --device 0000:01:00.0 ubuntu:noble
holos run --image-os openrc ./custom-alpine.qcow2
holos run alpine -- echo hello world

The synthesized compose file is stored at state_dir/runs/<name>/holos.yaml. The project name is derived from the image unless you pass --name.

Follow-up commands use the project name printed by holos run:

holos exec <name>
holos console <name>
holos logs <name>
holos down <name>

holos run exits once the VM is started. VMs are always detached. Use holos exec for an interactive shell and holos console for serial boot logs.

SSH With holos exec

Every holos up creates a project SSH key under state_dir/ssh/<project>/ and injects the public key with cloud-init. Each instance gets a host port forwarded to guest port 22.

holos exec web-0
holos exec db-0 -- pg_isready
holos exec my-project -- uname -a

-u <user> overrides the login user. Otherwise holos uses the service’s resolved cloud_init.user, then the image convention (alpine, arch, debian, fedora, ubuntu, almalinux, rocky, cloud-user), then ubuntu.

On a fresh VM, holos exec waits up to 60s for sshd to be ready. Use -w 0 to disable that wait or -w 5m for slow first boots.

Project Locks

Lifecycle commands take a per-project lock before reading or writing runtime state. holos up, run, down, start, stop, and ps -f wait up to --lock-timeout (default 5m) when another holos process is already operating on the same project. Use --no-wait when automation should fail fast instead of waiting:

holos up --lock-timeout 30s
holos down --no-wait demo

Lock errors include the lock path and last recorded holder metadata when available.

Inspection

holos inspect emits JSON for a project or instance:

holos inspect demo
holos inspect web-0
holos inspect -f holos.yaml
holos inspect -f holos.yaml web-0

Without -f, inspect reads runtime state: services, instances, host forwards, generated SSH endpoint, logs, QMP socket, and named-volume inventory. With -f, inspect also includes the resolved service manifest; instance inspection adds the QEMU argument vector reconstructed from the resolved manifest and saved instance paths. It does not read or print generated private key files.

Snapshots

Stopped instances can snapshot their root overlay with qemu-img:

holos stop -f holos.yaml web
holos snapshots create demo web-0 before-upgrade
holos snapshots list demo web-0
holos snapshots rm demo web-0 before-upgrade
holos snapshots restore demo web-0 before-upgrade
holos snapshots export demo web-0 before-upgrade ./web-before-upgrade.qcow2

Snapshot export creates a standalone qcow2 image; it can be copied to another host or used as a local image. Volume snapshots have equivalent snapshot-restore and snapshot-export commands under holos volumes.

The command refuses running instances because mutating an active qcow2 overlay outside QEMU is unsafe.

Image Verification

Built-in images carry checksum metadata. holos pull, holos up, and holos run verify downloads before promoting them into the cache and re-check a cached file before reuse. To audit the cache explicitly:

holos verify alpine
holos verify --all

holos images shows the guest OS metadata and hash algorithm used for each built-in entry. holos images lock -f holos.yaml writes holos.images.lock next to the compose file with each service’s resolved image path, format, size, and SHA-256 digest. Use -o <path> to choose a different lockfile path. When holos.images.lock exists next to the compose file, holos up verifies the current resolved images against it before launching anything.

Local image paths are not trusted by name; set image_format and image_os in compose, or --image-os with holos run, when a custom image does not match the defaults. For private qcow2 images, keep the generated project lockfile in source control; the threat model has a fuller checklist.

Reboot Survival

Install a systemd unit so a project comes back after host reboot:

holos install --enable
holos install --system --enable
holos install --dry-run
holos uninstall

User units go under ~/.config/systemd/user/holos-<project>.service; system units go under /etc/systemd/system/.

If you use holos install --system --user <name>, also pass an explicit --state-dir that the target user owns. holos keeps state directories owner-only.

Import From virsh

holos import reads libvirt domain XML and emits a starting holos.yaml:

holos import web-prod db-prod
holos import --all -o holos.yaml
holos import --xml ./web.xml
holos import --connect qemu:///system api

It maps vCPU, memory, machine type, host CPU mode, UEFI loader, the first file disk, extra qcow2 file disks, PCI host devices, bridged NIC intent, and USB hostdev metadata. Unsupported or review-needed parts are reported as warnings so you can edit the generated compose file before holos up.

Doctor

holos doctor checks the host without launching a VM:

holos doctor
holos doctor --json

It verifies Linux/KVM availability, QEMU tools, a cloud-init seed builder, SSH, optional OVMF firmware for UEFI and PCI passthrough, and state-dir writability.

Devices

holos devices --gpu lists VGA and 3D PCI devices with passthrough diagnostics:

holos devices --gpu

The output includes current driver binding, IOMMU group peers, same-slot audio pairing, NVIDIA UEFI/ROM hints, and suggested vfio-pci setup commands. It does not apply host changes.