CLI Reference

Version: 1.0

The vmlab command-line interface: lab lifecycle, per-VM and per-container control, snapshots, guest execution and scripting, playbooks, console and logs, template builds and OCI distribution, the network fast path, and the daemons.

§ 1Commands

- vmlab validate

- vmlab up

- vmlab down

- vmlab pull

- vmlab destroy

- vmlab status

- vmlab vm

- vmlab vm start

- vmlab vm stop

- vmlab vm restart

- vmlab vm destroy

- vmlab vm screenshot

- vmlab vm sendkeys

- vmlab vm mouse-move

- vmlab vm click

- vmlab vm drag

- vmlab vm ocr

- vmlab vm find-image

- vmlab container

- vmlab container start

- vmlab container stop

- vmlab container restart

- vmlab container destroy

- vmlab container exec

- vmlab container logs

- vmlab container ip

- vmlab container shell

- vmlab lab

- vmlab lab list

- vmlab lab info

- vmlab lab stop

- vmlab lab destroy

- vmlab snapshot

- vmlab snapshot create

- vmlab snapshot restore

- vmlab snapshot list

- vmlab snapshot delete

- vmlab playbook

- vmlab playbook list

- vmlab playbook check

- vmlab playbook apply

- vmlab exec

- vmlab shell

- vmlab cp

- vmlab tail

- vmlab eventlog

- vmlab osinfo

- vmlab script

- vmlab console

- vmlab logs

- vmlab template

- vmlab template build

- vmlab template list

- vmlab template rm

- vmlab template clean

- vmlab template export

- vmlab template import

- vmlab template search

- vmlab template registry

- vmlab template login

- vmlab template push

- vmlab template pull

- vmlab fastpath

- vmlab daemon

- vmlab daemon start

- vmlab daemon stop

- vmlab daemon status

§ 1.1vmlab validate

WCL schema + semantic validation of the lab, with no side effects. Run after editing vmlab.wcl and before up.

vmlab validate

§ 1.2vmlab up

Create linked clones, boot the VMs (a subset is optional), and run provision scripts in declaration order.

vmlab up
vmlab up dc01 client01

§ 1.3vmlab down

Graceful stop (guest agent → ACPI → kill). Linked clones are retained.

vmlab down

§ 1.4vmlab pull

Download missing registry templates/images for the lab's machines without starting anything.

vmlab pull

§ 1.5vmlab destroy

Stop the lab and DELETE its linked clones, lab-local state and dynamic network config. Destructive.

vmlab destroy

§ 1.6vmlab status

Show every machine's status and IP, plus the lab's segments. One row per VM and container, labelled in the words the web console uses.

vmlab status

vmlab status --verbose

§ 1.7vmlab vm

Per-VM power control and interaction: power, screenshot, keys/mouse, OCR and image matching.

vmlab vm start

Start a single VM.

vmlab vm start dc01

vmlab vm stop

Stop a single VM gracefully.

vmlab vm stop dc01

vmlab vm restart

Restart a single VM.

vmlab vm restart dc01

vmlab vm destroy

Destroy one VM: stop it and delete its clone (config retained; a later up rebuilds it).

vmlab vm destroy dc01

vmlab vm screenshot

Capture a running VM's screen to a PNG file.

vmlab vm screenshot dc01 screen.png

vmlab vm sendkeys

Send a key chord (see the key-chord reference).

vmlab vm sendkeys dc01 ctrl-alt-delete

vmlab vm mouse-move

Move the mouse pointer to absolute screen coordinates.

vmlab vm mouse-move dc01 640 400

vmlab vm click

Click a mouse button, optionally first moving to x,y (omit to click at the current position).

vmlab vm click dc01 640 400
vmlab vm click dc01 --button right

vmlab vm drag

Press, drag from x1,y1 to x2,y2, and release the left button.

vmlab vm drag dc01 100 100 400 300

vmlab vm ocr

OCR the VM's screen (optionally a region) and print the recognised text.

vmlab vm ocr dc01
vmlab vm ocr dc01 --region 0 0 800 100

vmlab vm find-image

Search the screen for a template image; prints match coordinates.

vmlab vm find-image dc01 ok-button.png

§ 1.8vmlab container

Per-container lifecycle, exec and logs (OCI containers run as micro-VMs, PRD §18).

vmlab container start

Start a single container.

vmlab container start web

vmlab container stop

Stop a container gracefully (stop signal → guest shutdown → kill).

vmlab container stop web

vmlab container restart

Restart a single container.

vmlab container restart web

vmlab container destroy

Stop and delete the container's writable overlay + pinned image digest; named volumes survive. A later up re-resolves the image.

vmlab container destroy web

vmlab container exec

Run a command inside the container; exits with the command's exit code.

vmlab container exec web -- nginx -t

vmlab container logs

Container stdout/stderr (the serial console log).

vmlab container logs web -f

vmlab container ip

The container's DHCP lease (errors on an air-gapped container).

vmlab container ip web

vmlab container shell

Attach an interactive shell inside the container's PID namespace (the workload is PID 1). Over the vmlab-agent virtio-serial channel — no container network needed. Ctrl-] detaches.

vmlab container shell web

§ 1.9vmlab lab

Manage running labs host-wide, by name (not the cwd's lab).

vmlab lab list

List every tracked lab: name, state, and directory.

vmlab lab list

vmlab lab info

Detailed status (VMs and segments) of a running lab.

vmlab lab info ad-demo

vmlab lab stop

Gracefully stop a running lab; clones retained.

vmlab lab stop ad-demo

vmlab lab destroy

Stop a lab and DELETE its clones and local state. Destructive.

vmlab lab destroy ad-demo

§ 1.10vmlab snapshot

Online (running: disk+RAM+device state) or offline (powered off: disk only) snapshots, per current power state. Restoring an online snapshot resumes running. Containers snapshot identically to VMs.

vmlab snapshot create

Create a snapshot. Omitting --vm snapshots every VM and container in the lab (best-effort, not coordinated).

vmlab snapshot create clean --vm dc01

vmlab snapshot restore

Restore a snapshot.

vmlab snapshot restore clean --vm dc01

vmlab snapshot list

List a VM's snapshots (name, taken_at, power_state).

vmlab snapshot list dc01

vmlab snapshot delete

Delete a VM's snapshot.

vmlab snapshot delete dc01 clean

§ 1.11vmlab playbook

Run config-weave playbooks (declared with playbook {} blocks) against lab machines. Exit codes mirror config-weave: 0 ok, 1 step error, 2 validation, 3 reboot still required after bounded retries.

vmlab playbook list

List the lab's playbook declarations and any in-flight runs.

vmlab playbook list

vmlab playbook check

Report drift without changing the guest (re-pushes the playbook first).

vmlab playbook check dc01

vmlab playbook apply

Push the playbook and converge the guest (auto-reboots when a step demands it).

vmlab playbook apply dc01

§ 1.12vmlab exec

Run a command in a guest and print its stdout/stderr over the vmlab-agent channel.

vmlab exec dc01 -- ipconfig /all

§ 1.13vmlab shell

Attach an interactive shell inside a VM: root bash on Linux, SYSTEM PowerShell (ConPTY) on Windows. Rides the vmlab-agent virtio-serial channel, so it works with no guest network. Each attach is a fresh, independent session; Ctrl-] detaches. Needs a template built with the agent (agent_version in its meta).

vmlab shell dc01

§ 1.14vmlab cp

Copy a file or directory between host and guest — either side may be <vm>:<path>. Parent directories are created. Agent transport: raw digest-verified bytes.

vmlab cp payload.zip dc01:C:/temp/payload.zip
vmlab cp dc01:C:/Windows/debug/netsetup.log ./netsetup.log

§ 1.15vmlab tail

Follow a file inside a guest (tail -F semantics over the agent channel — survives rotation; no network, no shell required).

vmlab tail web /var/log/nginx/access.log

§ 1.16vmlab eventlog

Follow the Windows event log of a guest over the agent channel.

vmlab eventlog dc01
vmlab eventlog dc01 --filter "*[System[(EventID=4624)]]"

§ 1.17vmlab osinfo

Print the guest OS identification the agent reports, as JSON: id (os-release ID, or windows), name, version, kernel, arch, hostname.

vmlab osinfo dc01

§ 1.18vmlab script

Run an ad-hoc wscript script against the running lab (entry point fn main(lab: Lab)).

vmlab script scripts/test.ws

§ 1.19vmlab console

Launch a VNC viewer for a VM (host config viewer command), or forward VNC over localhost TCP.

vmlab console dc01
vmlab console dc01 --tcp

§ 1.20vmlab logs

Print logs: lab events, or one VM's QEMU/serial output.

vmlab logs -f
vmlab logs dc01 -n 50
vmlab logs -o jsonl | jq .

§ 1.21vmlab template

Build, manage, and distribute disk templates. Local refs are <arch>/<name>[@<version>]; remote refs are host/repo:tag.

vmlab template build

Build the template {} blocks in a file (default ./vmlab.wcl). Name one to build just it.

vmlab template build
vmlab template build -f templates.wcl linux-modern

vmlab template list

List templates in the store.

vmlab template list --json
vmlab template list --remote

vmlab template rm

Remove a template from the store. The exact version is required.

vmlab template rm x86_64/linux-modern@1.0

vmlab template clean

Prune superseded builds, keeping the latest per template. Dry-run unless --yes; builds still backing a clone are skipped unless --force.

vmlab template clean            # dry run
vmlab template clean x86_64/linux-modern --yes

vmlab template export

Export a stored template to a portable archive.

vmlab template export x86_64/linux-modern@1.0 linux.tar.zst

vmlab template import

Import a template archive into the store.

vmlab template import linux.tar.zst

vmlab template search

Search the configured OCI registries. Uses VM registries by default; --kind container searches image registries.

vmlab template search alpine --arch x86_64
vmlab template search nginx --kind container

vmlab template registry

Manage OCI namespace settings shared by the CLI and web console.

vmlab template login

Log in to an OCI registry (persists to ~/.docker/config.json; existing docker logins are reused).

vmlab template login ghcr.io -u myuser -p <token>

vmlab template push

Push a stored template to a registry as an OCI artifact (chunked, multi-arch capable). Moves the latest tag (or latest-prerelease with --prerelease) and links the package to a source repo.

vmlab template push x86_64/linux-modern@1.0 ghcr.io/owner/linux-modern:1.0

vmlab template pull

Pull a template from a registry into the store. --arch is required for multi-arch indexes.

vmlab template pull ghcr.io/owner/linux-modern:1.0 --arch x86_64

§ 1.22vmlab fastpath

Show which network fast-path tier is active (userspace / afxdp / sockmap) — and why the others are not.

vmlab fastpath

§ 1.23vmlab daemon

Manage the supervisor daemon. It is auto-started by any other verb, so this is rarely needed.

vmlab daemon start

Start the supervisor (auto-started by any other verb anyway).

vmlab daemon start

vmlab daemon stop

Stop the supervisor and all lab daemons.

vmlab daemon stop

vmlab daemon status

Show supervisor version and running labs (name/state/pid/root).

vmlab daemon status