CLI Reference
Version: 1.0
The vmlab command-line interface: lab lifecycle, per-VM power, snapshots, guest execution and scripting, console and logs, template builds and OCI distribution, and the daemons.
§ 1Commands
- vmlab up
- vmlab vm
§ 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.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm… | optional | Optional VMs to bring up; omit for the whole lab. | — |
vmlab up
vmlab up dc01 client01§ 1.3vmlab down
Graceful stop (guest agent → ACPI → kill). Linked clones are retained.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm… | optional | Optional VMs to stop; omit for the whole lab. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --force | — | Skip the graceful ladder and kill immediately. | — |
vmlab down§ 1.4vmlab destroy
Stop the lab and DELETE its linked clones, lab-local state and dynamic network config. Destructive.
vmlab destroy§ 1.5vmlab status
Show lab / VM / segment state, IPs and ready flags.
vmlab status§ 1.6vmlab vm
Per-VM power control.
vmlab vm start
Start a single VM.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
vmlab vm start dc01vmlab vm stop
Stop a single VM gracefully.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --force | — | Kill immediately instead of the graceful ladder. | — |
vmlab vm stop dc01vmlab vm restart
Restart a single VM.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
vmlab vm restart dc01§ 1.7vmlab snapshot
Online (running: disk+RAM+device state) or offline (powered off: disk only) snapshots, per current power state. Restoring an online snapshot resumes running.
vmlab snapshot create
Create a snapshot. Omitting --vm snapshots every VM in the lab (best-effort, not coordinated).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| name | required | Snapshot name. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --vm | VM | Target a single VM; omit for the whole lab. | — |
vmlab snapshot create clean --vm dc01vmlab snapshot restore
Restore a snapshot.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| name | required | Snapshot name. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --vm | VM | Target a single VM; omit for the whole lab. | — |
vmlab snapshot restore clean --vm dc01vmlab snapshot list
List a VM's snapshots (name, takenat, powerstate).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
vmlab snapshot list dc01vmlab snapshot delete
Delete a VM's snapshot.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
| name | required | Snapshot name. | — |
vmlab snapshot delete dc01 clean§ 1.8vmlab exec
Run a command in a guest via the guest agent and print its stdout/stderr.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
| cmd… | required | Command and arguments, after --. | — |
vmlab exec dc01 -- ipconfig /all§ 1.9vmlab script
Run an ad-hoc wscript script against the running lab (entry point fn main(lab: Lab)).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| script.ws | required | Path to the wscript file. | — |
vmlab script scripts/test.ws§ 1.10vmlab console
Launch a VNC viewer for a VM (host config viewer command), or forward VNC over localhost TCP.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| vm | required | VM name. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --tcp | — | Forward VNC over a localhost TCP port instead of launching the viewer (WSL2 / remote viewers). | — |
vmlab console dc01
vmlab console dc01 --tcp§ 1.11vmlab logs
Print JSON-line logs: lab events, or one VM's QEMU/serial output.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| [lab/][vm] | optional | Lab events (default) or a specific VM's logs. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| -f, --follow | — | Follow the log as it grows. | — |
| -n, --lines | N | Lines of history (default 100). | — |
vmlab logs -f
vmlab logs dc01 -n 50§ 1.12vmlab 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.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| name | optional | A single template to build; omit to build all. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| -f, --file | FILE | WCL file containing the template {} blocks (default ./vmlab.wcl). | — |
vmlab template build
vmlab template build -f templates.wcl linux-modernvmlab template list
List templates in the store.
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --json | — | Emit the full metadata array (ref, sizes in bytes, RFC 3339 created). | — |
vmlab template list --jsonvmlab template rm
Remove a template from the store. The exact version is required.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| <arch>/<name>@<version> | required | Exact store ref including version. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --force | — | Remove even if linked clones back it. | — |
vmlab template rm x86_64/linux-modern@1.0vmlab template export
Export a stored template to a portable archive.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| <arch>/<name>[@<ver>] | required | Store ref to export. | — |
| out.tar.zst | required | Output archive path. | — |
vmlab template export x86_64/linux-modern@1.0 linux.tar.zstvmlab template import
Import a template archive into the store.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| archive.tar.zst | required | Archive to import. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --overwrite | — | Replace an existing store entry. | — |
vmlab template import linux.tar.zstvmlab template login
Log in to an OCI registry (persists to ~/.docker/config.json; existing docker logins are reused).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| registry | required | Registry host, e.g. ghcr.io. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| -u, --user | USER | Registry username. | — |
| -p, --password | TOKEN | Password or token. | — |
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).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| <arch>/<name>[@<ver>] | required | Local store ref. | — |
| registry/repo:tag | required | Remote registry ref. | — |
vmlab template push x86_64/linux-modern@1.0 ghcr.io/owner/linux-modern:1.0vmlab template pull
Pull a template from a registry into the store. --arch is required for multi-arch indexes.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| registry/repo:tag | required | Remote registry ref. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --arch | ARCH | Required when the remote is a multi-arch index. | — |
vmlab template pull ghcr.io/owner/linux-modern:1.0 --arch x86_64§ 1.13vmlab 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 startvmlab daemon stop
Stop the supervisor and all lab daemons.
vmlab daemon stopvmlab daemon status
Show supervisor version and running labs (name/state/pid/root).
vmlab daemon status