# vm-cli Complete Command-Line Manual

vm-cli is a standalone program for creating, running, viewing, and controlling local virtual machines. Use `vm-cli.exe` on Windows and the matching `vm-cli` build on macOS/Linux. This manual is embedded in the executable and works offline without external documentation or helper programs.

> **AI agents: run `setup` to install the vm-cli Skill for your client before first use.** The Skill provides a fixed executable path, VM data directory, version checks, installation-media discovery, screenshot observation, control ownership, and recovery instructions. Installation is recommended, not required for ordinary commands. For an existing installation, first run `setup --action check --clients codex`. After upgrading, run `setup --action update --clients codex` from the new executable and reload the Skill.

```powershell
.\vm-cli.exe setup --clients codex
.\vm-cli.exe setup --clients claude-code
.\vm-cli.exe setup --clients opencode
```

Help is English Markdown, independent of the GUI language. Business commands continue to return JSON. A terminal or agent invocation without arguments, `--help`, and `help` all print this same complete manual. `create --help`, `media attach --help`, and similar requests print the relevant command instructions. Help never creates VMs, installs Skills, opens a GUI, or starts a Web service. Direct double-click in Windows Explorer keeps the existing manager entry point; launch the bare macOS executable from a terminal.

Windows uses a standard console executable. Run commands directly in CMD, PowerShell, or an agent process: ordinary foreground calls wait for completion and provide the command's exit code. Standard input, output, error output, JSON pipelines, and file redirection work normally; no special shell waiting wrapper is required. Double-clicking the executable in Explorer opens the manager and releases its temporary console; a brief console flash is expected and accepted. A headless agent is never treated as an Explorer launch just because it has no console. Explicit `manager`, `tray`, and `view` commands remain available. No additional launcher EXE or DLL is required.

## overview — Capabilities, navigation, and conventions

Features include machine presets; CPU, memory, firmware, display, audio, and network settings; disk, CD-ROM, and floppy management; headless operation by default; PNG screenshots; keyboard, mouse, and wheel input; native SDL display windows, manager, and tray; HTTPS Web and LAN access; H.264 MP4 recording; data-directory management; owned-disk cleanup; vm-cli Cloud device sign-in, verified private-version download, independent local reconstruction and cache cleanup; and historical compatibility queries.

Platform builds support Windows 10/11 x64, Linux x64/ARM64, and macOS Intel x64/Apple Silicon ARM64. The Intel Mac build is qualified on macOS 12.7.6; the Apple Silicon build is qualified on macOS 26.5.1. These are separate architecture-specific qualification results, not a universal macOS minimum. Use `capabilities` to inspect the presets and devices in your executable. Hardware acceleration uses WHPX, HVF, or KVM; software execution uses TCG. Each architecture requires its matching build; arbitrary cross-architecture virtualization is not promised. Ordinary desktop 2D display is supported, but guest 3D/GPU acceleration and cycle-accurate vintage hardware emulation are not.

`create` prepares the machine and disks; it does not install an OS, drivers, or applications. When tasked with installing an OS, an agent should continue by finding appropriate media, attaching it, booting, completing installation through screenshots and input, and verifying the actual guest desktop. There is no built-in ISO downloader, automatic installation command, arbitrary guest shell/file-copy command, snapshot command, or clone command. Upstream QEMU options are not public vm-cli options.

| Command/topic | Purpose and help example |
| --- | --- |
| `setup` | Install, check, update, remove, or export the AI Skill: `setup --help` |
| `service` | Manage the Windows network service: `service --help` |
| `version`, `host inspect`, `doctor`, `capabilities`, `preset` | Version, host, diagnostics, capabilities, and presets: `preset --help` |
| `create`, `list`, `show`, `start`, `delete` | Machine lifecycle: `create --help` |
| `shutdown`, `poweroff`, `reset`, `reboot` | Graceful shutdown, forced power-off, hard reset, and graceful reboot limitations |
| `config`, `device`, `media`, `storage`, `firmware`, `network` | Configuration, peripherals, media, disks, firmware, and networking |
| `screen`, `input`, `control` | Observe the display, send input, and manage exclusive control sessions |
| `view`, `manager`, `tray`, `web` | Explicit native or Web graphical entry points |
| `root`, `media-catalog` | Register data directories and media available to the browser |
| `record` | Start, inspect, and stop screen recording |
| `login`, `logout` | Sign in or remove the local Cloud session |
| `cloud push`, `cloud pull` | Inspect/upload a stopped VM or download and verify an immutable Cloud version |
| `run` | Create/start an independent local VM from a private or official Cloud version |
| `cloud account`, `cloud catalog`, `cloud list`, `cloud repository`, `cloud versions`, `cloud version`, `cloud trash`, `cloud quota`, `cloud cache`, `cloud task` | Inspect the signed-in account and active official catalog; manage private repositories and immutable versions, recoverable trash, authoritative capacity, verified local caches, and durable transfer tasks |
| `request`, `compatibility` | Inspect an earlier request or historical compatibility evidence |
| `global`, `configuration`, `results`, `workflow` | Global options, complete configuration fields, results/errors, and an end-to-end example: e.g. `help workflow` |

```powershell
.\vm-cli.exe --help
.\vm-cli.exe create --help
.\vm-cli.exe media attach --help
.\vm-cli.exe help workflow
.\vm-cli.exe version
.\vm-cli.exe list
```

Examples use Windows PowerShell: `.\vm-cli.exe` for the current directory, or `& 'E:\Tools\vm-cli.exe'` for an absolute path. In CMD, use `vm-cli.exe`; on macOS/Linux, use `./vm-cli` and platform-appropriate paths. Quote names and paths containing spaces. Pass options as `--option value`, not `--option=value`. Boolean switches take no `true/false` value. Do not repeat an option.

`<vm>` means the actual `vm_id` or full name within the selected `--root`. Agents should call `list` first and prefer the stable `vm_id` thereafter. Examples such as `vm-ACTUAL_ID`, `session-ACTUAL_ID`, `record-ACTUAL_ID`, `disk-ACTUAL_ID`, and `CURRENT_REVISION` are placeholders: replace them with real returned values. Do not type angle brackets literally into the shell. After each configuration change, use the returned `config_revision` for the next change.

## service — Manage the Windows network service

Windows x64 distributes one signed EXE. The same program supplies a LocalSystem network service in a protected version directory. Install it once for the Windows user who will run vm-cli. Subsequent Agent, GUI, and Web bridge operations use authenticated local IPC without requesting administrator elevation. The service accepts fixed network operations, not arbitrary commands. SeLow does not migrate host IP addresses, routes, or DNS. Independent NAT does not require this service.

Client and service **product version and build ID must both match exactly**. A mismatch returns `SERVICE_VERSION_MISMATCH`, without automatically updating or requesting elevation. Explicitly update using the intended newly downloaded EXE; old clients are then rejected. VM files and network definitions remain intact, but idle bridge bindings require explicit ordinary-user re-preparation for the new build.

### service install — Install and authorize this Windows user

Syntax: `vm-cli.exe service install [--plan] [--request-id ID]`. The real operation requests administrator approval, verifies the signed EXE, installs a protected copy, starts the service and persistently authorizes the originating Windows SID. Another user requires its own explicit installation authorization. A different installed version/build requires `service update`. `--plan` is read-only.

Example: `.\vm-cli.exe service install --request-id service-install-001`.

### service status — Inspect the service or original maintenance request

Syntax: `vm-cli.exe service status [--request-id ID]`. Reports installation, running state, both identities and this user's authorization. Mismatching services remain inspectable. With the original install/update/uninstall request ID, reads the protected maintenance journal and its original result or unresolved state. It never repeats a mutation or requests elevation.

### service start — Start the installed matching service

Syntax: `vm-cli.exe service start`. An already authorized Windows user can start the service without elevation. It does not install or update anything. Windows also starts the service automatically at boot.

### service stop — Stop an idle matching service

Syntax: `vm-cli.exe service stop`. Uses authenticated IPC without elevation. Active or unresolved bridge ports, including other users' ports, return `NETWORK_IN_USE`. Stop affected VMs or recover their original resources first. There is no force-stop option.

### service restart — Restart an idle matching service

Syntax: `vm-cli.exe service restart`. Applies stop/start's identity, authorization and idle checks. After a lost reply inspect `service status` before taking further action; restart is not a durable maintenance transaction.

### service update — Replace the protected service with this EXE

Syntax: `vm-cli.exe service update [--plan] [--request-id ID]`. Requires explicit administrator approval. Verifies and stages the new EXE before stopping the old one, rejects active/unresolved ports, retires known idle SeLow bindings, changes registration and verifies the new running identity. Failure attempts to restore the old executable, running state, permissions and binding records, reporting whether recovery was confirmed. No automatic downgrade or cross-build compatibility is allowed.

Example: `& 'C:\Downloads\vm-cli.exe' service update --request-id service-update-002`.

Persist a request ID before install/update/uninstall. After a timeout query `service status --request-id ID`; do not replace an unresolved request with a new one. Identical completed requests return the original result without another elevation prompt; different operations cannot reuse an ID. Refresh the Agent Skill separately using the new EXE's `setup --action update`.

### service uninstall — Remove the idle service registration

Syntax: `vm-cli.exe service uninstall [--plan] [--request-id ID]`. Requires administrator approval. First stop bridge VMs and remove bridge authorizations. Active/unresolved ports or remaining grants prevent uninstall. Removes the registration and persistent authorization, retaining VM data, disks, configuration, historical receipts and the shared driver. It never recursively deletes user directories.

### service delete — Alias for service uninstall

Syntax: `vm-cli.exe service delete [--plan] [--request-id ID]`. Same scope and checks as uninstall; it does not delete VMs.

Service maintenance is a local CLI operation, unavailable through Web. These Windows commands return `UNSUPPORTED_PLATFORM` on other platforms.

## global — Global options, directories, and execution

Syntax: `vm-cli.exe [global-options] command [subcommand] [positional-arguments] [command-options]`. Options may appear before or after the command. Command-specific options apply only to their respective operations; do not pass them to unrelated commands.

| Option | Type/default | Meaning and constraints |
| --- | --- | --- |
| `--help` | Switch; no value | Print the complete Markdown manual, or the relevant help when combined with a command. That command's otherwise required positional arguments may be omitted |
| `--version` | Switch; no value | Equivalent to `version`; the result remains JSON |
| `--root DIRECTORY` | Optional local scope; selected directory for creation | Limits discovery and VM resolution to one local directory. Without it, existing VM references/names resolve across registered roots; create/run and non-VM storage operations use the selected directory. This is not the executable directory. Also pins the Skill's VM directory during setup |
| `--json` | Switch; no value | Preserve the JSON business-result interface; business commands already default to JSON. Help always remains Markdown, even with this switch |
| `--request-id ID` | String; generated by default | 1–100 ASCII letters, digits, underscores, or hyphens. Associates a fixed ID with the request. Only some mutations support persisted result lookup; see request |
| `--timeout MILLISECONDS` | Integer milliseconds; RPC default 15000, start default 30000 | Range 1–300000 for ordinary commands. Whole-VM `cloud push`, `cloud pull`, `run`, and `cloud task resume` allow 1–86400000 and default to 86400000 (24 hours); individual HTTPS calls remain bounded to at most 300000. Limits this invocation's wait, not guest completion; timeout never automatically powers off the VM. setup does not accept it |

```powershell
.\vm-cli.exe --root 'E:\VMs' list
.\vm-cli.exe --root 'E:\VMs' --request-id my-start-001 start 'Linux Lab' --timeout 60000
.\vm-cli.exe --root 'E:\VMs' request show my-start-001
```

The default root is `%LOCALAPPDATA%\vm-cli\data` on Windows; `$HOME/Library/Application Support/vm-cli/data` on macOS (an absolute `VMCLI_DATA_HOME` can override its parent directory); and `$XDG_DATA_HOME/vm-cli/data` or `$HOME/.local/share/vm-cli/data` on Linux. `root select` changes the destination used by creation and root-scoped storage/network commands when `--root` is omitted; it does not narrow default `ls` or existing-VM resolution.

`manager`, `tray`, `web`, `root`, and `media-catalog` manage registrations belonging to the current host user. `--root` cannot turn them into a separate host service. Creating or starting a VM with `--root` automatically registers that directory for the current user; `root register` also adds an existing portable directory without starting anything. VM configuration, owned disks, screenshots, logs, recordings, and writable UEFI state are saved under the data directory. Embedded BIOS/UEFI/ROM resources are cached as data files when needed. The runtime does not extract companion EXE/DLL files.

`start` does not open the VM display. On a local desktop it creates or reuses the current user's tray/menu-bar entry, with manager and VM actions. Linux sessions without a desktop remain headless. `view` and `manager` explicitly open windows; `tray` explicitly creates or reuses the tray. Exiting the CLI, closing a Viewer, or quitting the tray does not shut down a VM. Commands run as the current host user; host permissions still govern data access and control sessions.

## setup — Install the AI agent Skill

Syntax: `vm-cli.exe setup [--action install|check|update|remove|export] [--clients CLIENTS] [--scope user|project] [--project DIRECTORY] [--root DIRECTORY] [--dry-run] [--output DIRECTORY]`.

**Agents should install the Skill for their client before first use.** Ordinary commands do not require setup. This configures Skill + CLI only: it does not create an MCP service, install a model client, or require a model-account login. The Skill records the absolute executable path and build identity of the program running setup. Run it from the new executable you intend to use.

| Option | Default/requirement | Meaning |
| --- | --- | --- |
| `--action install` | Default when clients are supplied | Install, or refresh an existing managed Skill that the user has not modified |
| `--action check` | Clients may be omitted to check all three | Check paths, file modifications, and version binding; does not prove that a client loaded the Skill or that its model understands screenshots |
| `--action update` | Requires an existing managed installation | Bind to this executable; returns NOT_FOUND if not installed |
| `--action remove` | Select clients | Remove the selected client's managed Skill; retain a shared directory still used by another client. Does not delete VMs |
| `--action export` | Requires output | Export the Skill to a directory; defaults to codex if clients are omitted |
| `--clients CLIENTS` | Comma-separated; no duplicates | `codex`, `claude-code`, or `opencode`; multiple clients may be selected |
| `--scope user` | Default | Install for the current user |
| `--scope project` | Optional | Install for a project, separately from user scope |
| `--project DIRECTORY` | Current working directory in project scope | Valid only with `--scope project`; this is not the VM data root |
| `--root DIRECTORY` | Existing installation's binding; currently selected root for a new installation | Pin the Skill's VM directory. Updates preserve its existing directory unless an explicit replacement is supplied |
| `--dry-run` | Switch; no value | Return the plan and conflicts without writing the Skill |
| `--output DIRECTORY` | Required for export only | Export destination; rejected for other actions |

Interactive `setup` without clients prompts for the client and action. In an agent/pipe environment, specify `--clients` to avoid waiting for input or SETUP_SELECTION_REQUIRED. User modifications or an unmanaged Skill with the same name cause SETUP_CONFLICT; preserve those changes before resolving the conflict. After installation or an update, reload the Skill, read installation.json, and call version/capabilities through its recorded absolute path. Do not silently use a different executable from PATH.

```powershell
.\vm-cli.exe setup
.\vm-cli.exe setup --action install --clients codex
.\vm-cli.exe setup --clients claude-code,opencode
.\vm-cli.exe setup --action check --clients codex
.\vm-cli.exe setup --action update --clients codex --root 'E:\VMs'
.\vm-cli.exe setup --clients codex --scope project --project 'E:\Projects\Lab' --root 'E:\VMs' --dry-run
.\vm-cli.exe setup --action remove --clients opencode
.\vm-cli.exe setup --action export --clients codex --output 'E:\Exports\vm-cli-skill'
```

## preferences — Set native interface language and appearance

Preferences belong to the current host user and are shared by the native GUI and CLI on Windows, Linux and macOS. They do not depend on a VM or data root. CLI JSON keys, error codes and help language are unchanged.

### preferences show — Inspect saved and resolved preferences

Syntax: `vm-cli.exe preferences show`. Returns `saved.locale`, `saved.theme`, and the resolved locale and text direction. When theme is `system`, `resolved.theme` is null and `theme_source` is `native-system`: the native window resolves the operating system appearance. This command does not start a graphical session.

### preferences set — Change only specified preferences

Syntax: `vm-cli.exe preferences set [--locale LOCALE] [--theme system|light|dark]`. Supply at least one option. Locale accepts `system`, `en`, `zh-CN`, `zh-TW`, `es`, `fr`, `de`, `pt-BR`, `ru`, `ja`, `ko`, `ar`, or `hi`.

Values are validated before saving. Unspecified settings and unknown future fields are preserved; updates share a file lock and are written atomically. A corrupt preference file is not silently overwritten. CLI changes apply to newly launched GUI processes. Existing windows keep their current appearance and edit values; their language/theme menus still apply changes immediately. This avoids changing part of an open window halfway through an edit.

```powershell
.\vm-cli.exe preferences set --locale en --theme dark
.\vm-cli.exe preferences show
```

## version — Identify the running executable

Syntax: `vm-cli.exe version` or `vm-cli.exe --version`. No required arguments. Returns the product version, actual executable path, platform, build_id, build kind, Skill contract version, result/config schema versions, engine version, and firmware bundle digest. It identifies the file being executed; it does not check online for updates. Example: `.\vm-cli.exe version`.

## host — Inspect the host

### host inspect — Hardware acceleration and prerequisites

Syntax: `vm-cli.exe host inspect`. No command-specific options. Reports the actual host architecture and WHPX/HVF/KVM availability probes. An available acceleration API does not guarantee successful initialization or compatibility with every guest. Does not enable system features. Example: `.\vm-cli.exe host inspect`.

On Windows x64, `pentium3` with `execution=required` is a bounded legacy WHPX profile: i440fx, BIOS and one CPU, basic CPUID leaves limited to 3, and userspace interrupt-controller emulation. Guest instructions still use WHPX; there is no TCG fallback. Select the same CPU and execution mode in native/Web Compute settings. Other legacy CPUs still require software execution. This profile does not certify every old Windows release or reproduce the timing of a physical Pentium III.

## doctor — Diagnose host prerequisites

Syntax: `vm-cli.exe doctor`. No command-specific options; currently uses the same host probe as host inspect. For ACCEL_UNAVAILABLE, inspect this result and the VM's execution setting. It does not automatically change BIOS settings, system virtualization features, or the firewall. Example: `.\vm-cli.exe doctor`.

## capabilities — Inspect this build's actual capabilities

Syntax: `vm-cli.exe capabilities`. No command-specific options. Returns CPU, machine, display, audio, network, input, and storage models; presets; firmware types; compiled accelerators; recording/Viewer features; and explicit limitations. Available presets differ by host/guest architecture build. Do not assume that a preset absent from this result is supported. Example: `.\vm-cli.exe capabilities`.

## preset — Inspect machine templates

Presets are hardware templates. They include no installation media and do not establish that all old operating systems have been tested. Audio and serial output initially default to off. Creation assigns a new vm_id and config_revision.

| ID | Architecture/machine | CPU/count | Memory MiB | Default disk MiB at creation | Execution, firmware, input, network defaults |
| --- | --- | --- | --- | --- | --- |
| dos | x86 / i440fx | 486 / 1 | 32 | 64 | software, BIOS, PS/2, off |
| win9x | x86 / i440fx | pentium / 1 | 128 | 2048 | software, BIOS, PS/2, off |
| traditional | x86 / i440fx | pentium3 / 1 | 512 | 10240 | software, BIOS, PS/2, off |
| modern-x64 | x86_64 / Q35 | max / 2 | 2048 | 32768 | required, UEFI, USB tablet, NAT |
| arm64 | aarch64 / virt | max / 2 | 2048 | 32768 | required, UEFI, USB tablet, NAT |

Legacy x86 presets provide disk0, cd0, and floppy0; modern-x64 provides disk0 and cd0; arm64 uses VirtIO disks and a SCSI CD-ROM. x86 builds do not provide arm64, and ARM64 builds do not provide x86 presets. Read the full returned object for bus/slot details, boot_order, and the firmware digest.

### preset list — List available presets

Syntax: `vm-cli.exe preset list`. No command-specific options. Returns all templates available in this build. Example: `.\vm-cli.exe preset list`.

### preset show — Inspect one preset

Syntax: `vm-cli.exe preset show <id>`. Required `id` is a preset available in this build, as listed above. Example: `.\vm-cli.exe preset show dos`. Returns a hardware template, not a replacement for an existing VM's complete config apply document.

## create — Create a machine and optional disk

Syntax: `vm-cli.exe create <name> [--preset ID] [--disk-mib N] [--execution software|required] [--memory-mib N] [--cpu MODEL] [--cpus N]`.

| Argument/option | Required/default | Meaning, range, and dependencies |
| --- | --- | --- |
| name | Required | Unique within this root; 1–200 UTF-8 bytes. Quote spaces |
| `--preset ID` | modern-x64 on x86; arm64 on ARM64 | Start from a template returned by preset list; see preset for available IDs |
| `--disk-mib N` | Preset-specific; see preset table | 0–16777216 MiB (up to 16 TiB). Zero creates no disk file; a nonzero value creates an internal writable disk0.qcow2 with this virtual capacity |
| `--execution software|required` | Preset-specific | software explicitly uses TCG; required must initialize host hardware acceleration successfully and never silently falls back |
| `--memory-mib N` | Preset-specific | Integer MiB: x86 4–1048576, ARM64 128–1048576; actual host resources still limit use |
| `--cpu MODEL` | Preset-specific | x86: 486/pentium/pentium2/pentium3/qemu64/max; ARM64: max/cortex-a72. Hardware execution uses max (also qemu64 on x86). Windows also permits pentium3 with i440fx, BIOS and one CPU; other legacy models require software. |
| `--cpus N` | Preset-specific | Integer 1–64; 486/pentium require exactly one CPU |

Returns the complete configuration, including vm_id, config_revision (initially 1), and disk references. Does not start the VM or install an OS. Inspect capabilities first if needed. A fixed request-id lets you inspect the same creation request later. Firmware caches and disks are written as ordinary data files under the root.

```powershell
.\vm-cli.exe --root 'E:\VMs' --request-id create-dos-001 create 'DOS Lab' --preset dos --disk-mib 128
.\vm-cli.exe create 'Windows 3.11' --preset dos --memory-mib 32 --cpu 486 --cpus 1
.\vm-cli.exe create 'Linux Lab' --preset modern-x64 --memory-mib 4096 --cpus 2 --disk-mib 32768
.\vm-cli.exe create 'Empty DOS' --preset dos --disk-mib 0
```

## list — List available VMs

Syntax: `vm-cli.exe list [--local | --node NODE | --cloud] [--root DIRECTORY] [--format json|table] [--timeout MILLISECONDS]`.

`ls` is an exact alias. Without an explicit root, aggregate the current user's registered local directories. Return `data.schema=vm-cli-inventory/1`, `machines`, `sources`, `errors`, `complete`, and observation times. This changes the older array response and single-selected-root default. Use `data.machines`, and check `complete` before relying on name uniqueness. An explicit `--root` retains a single-directory scope. Missing directories remain source errors and are never recreated by listing. If all selected sources fail, return `INVENTORY_UNAVAILABLE`.

Each row includes `vm_id`, `ref`, `node_id`, `root_id`, placement/config revisions, VM power state and source connection state. Local rows also contain `root_path`; remote rows never expose host paths. A full local `node-ID/vm-ID` reference routes existing-VM commands to the same local root. Names shared by two roots return `AMBIGUOUS_NAME`; incomplete discovery returns `INVENTORY_INCOMPLETE` for an unprovable name. Copied permanent identities are conflicts, not an excuse to rewrite disks or IDs. Complete refs and explicit local root constraints cannot select a different object silently.

JSON is the default. `--format table` prints human-readable text and identifies each node. A node-enabled build also queries enrolled nodes when normal Cloud sign-in and the node data API are available. `--node NODE` selects an enrolled ID or exact name; `--local` and `--root` make no Cloud credential or network request. Without sign-in, the default query still returns local results with `remote_sources.state=not_authenticated`. An unavailable node or directory makes the combined result incomplete; it does not turn its VMs into stopped VMs. Partially observed rows have unknown current state, and `ps` includes only confirmed running rows. The query has a total deadline and fixed source/item bounds; exceeding a bound is explicit in the incomplete result. A local node ID does not register this computer with Cloud. Hosted compute (`--cloud`) remains unavailable; Cloud image storage does not provide rented compute. Remote mutation, GUI/Web parity and five-platform qualification are still under development; this source help does not change the published P1 capability set.

## ls — Alias for list

Syntax and JSON response are exactly the same as `list`. Example: `vm-cli.exe ls --format table`.

## ps — List confirmed running VMs

Uses the same scope and filters as `ls`, selecting only currently confirmed `running` instances. Offline roots and unknown runtime observations remain in completeness and unverified metadata; absence from this view does not prove a VM stopped. Paused, starting and failed states remain visible in `ls`.

## show — Inspect configuration and runtime state

Syntax: `vm-cli.exe show <vm>`. The VM is required. Returns `data.config` and `data.runtime`, including configuration revision, devices, and runtime state. Example: `.\vm-cli.exe show 'DOS Lab'`. This is an observation, not a guarantee that another caller cannot change configuration before your next operation.

## start — Start headless

Syntax: `vm-cli.exe start <vm> [--timeout MILLISECONDS]`. The VM is required. Default wait is 30000 milliseconds; range 1–300000. Starts from the saved configuration; create's hardware options cannot be used here to change the machine temporarily. Repeated start requests do not create a second runtime. A successful runtime result does not mean the guest OS has finished booting; continue observing screenshots.

If required acceleration cannot initialize, returns ACCEL_UNAVAILABLE without switching to software. OUTCOME_UNKNOWN means this wait did not establish the result; query the original request-id and show with the same root instead of creating another machine. Example: `.\vm-cli.exe --request-id start-dos-001 start 'DOS Lab' --timeout 60000`.

## shutdown — Request graceful shutdown

Syntax: `vm-cli.exe shutdown <vm> [--session-id ID --epoch N]`. The VM is required; use session arguments when holding control. Requires a running VM. RPC wait defaults to 15000 milliseconds and can be changed with timeout. Sends a guest power-shutdown request and returns accepted with guest_shutdown_confirmed=false. The guest may not support it or may still be shutting down. Poll show for stopped; a timeout never automatically forces power off. Example: `.\vm-cli.exe shutdown 'Linux Lab'`.

## poweroff — Force power off

Syntax: `vm-cli.exe poweroff <vm> [--session-id ID --epoch N]`. Requires a running VM; no other command-specific options. Supports timeout. Immediately forces guest power off; unsaved data may be lost. Respects control ownership. Use show to verify stopped afterwards. Example: `.\vm-cli.exe poweroff 'DOS Lab'`.

## reset — Perform a hard reset

Syntax: `vm-cli.exe reset <vm> [--session-id ID --epoch N]`. Requires a running VM; no other command-specific options. Supports timeout. Equivalent to a hardware reset: loses unsaved guest state and releases held input and the current control session. This is not a graceful OS reboot. Example: `.\vm-cli.exe reset 'DOS Lab'`.

## reboot — Current graceful reboot limitation

Syntax: `vm-cli.exe reboot <vm> [--session-id ID --epoch N]`. The VM is required. No guest cooperation mechanism is currently available, so this returns NOT_SUPPORTED rather than silently performing reset. For a graceful reboot, use the guest's own menus/input and observe the process. Example: `.\vm-cli.exe reboot 'Linux Lab'` (currently expected to return an unsupported-operation error).

## delete — Remove VM registration while retaining data

Syntax: `vm-cli.exe delete <vm>`. The VM is required; there is no disk-erasure option. The VM must be stopped, with no recording in starting/recording/finalizing. Logically deletes the instance and saves a retention manifest. Original instance files and disks remain in place; external media is unchanged. Returns deletion_id, retained_path, and retention_manifest. Use storage cleanup separately for eligible owned disks; deletion never implicitly erases disks. Example: `.\vm-cli.exe delete 'Empty DOS'`.

## config — Read, validate, and replace complete configuration

Common arguments: vm identifies an instance in the current root; `--file JSON` is a UTF-8 JSON file containing a complete configuration object, not a patch or the CLI's ok/data result envelope; `--revision N` is the current positive config_revision and is required for apply. See `help configuration` for fields. Applying hardware configuration requires a stopped VM.

### config show — Read configuration

Syntax: `vm-cli.exe config show <vm>`. No command-specific options. Returns the complete configuration in `data`. Example: `.\vm-cli.exe config show 'DOS Lab'`.

### config resources — Read the selected execution node's saved resources

Use the existing hardware commands with a complete registered-node VM reference:

```text
vm-cli device add NODE_ID/VM_ID --file device.json --revision N
vm-cli device update NODE_ID/VM_ID --file device.json --revision N
vm-cli device remove NODE_ID/VM_ID --device disk1 --revision N
vm-cli storage create NODE_ID/VM_ID --device disk1 --disk-mib 1024 --format qcow2 --revision N
vm-cli media eject NODE_ID/VM_ID --device disk1 --revision N
vm-cli media catalog NODE_ID/VM_ID
vm-cli media attach NODE_ID/VM_ID --device disk1 --asset disk-ASSET_ID --asset-revision SHA256 --readonly --revision N
```

The device file is read on the calling client and contains only `id`, `kind`, `bus` and integer `slot`. The node checks its own architecture and current configuration. The new virtual disk is created inside that VM's node-owned directory; no physical disk or arbitrary node path can be selected. Removing devices and ejecting media retain disk files. Use `device list VM_REF`, `media list VM_REF` and `config resources VM_REF` to inspect the target; remote media are scoped references, not local paths. Each mutation returns its original task reference: on an uncertain result, use `request show REQUEST_REF` instead of issuing another request. Normal manager rights and revision/stopped/control checks apply. External-media registration/upload remain separate work.

Retained-media attachment uses `media catalog VM_REF` (or `config resources VM_REF` → `retained_media`). The catalog contains only product-owned retained disks belonging to that exact VM, including ejected disks, with asset ID/revision, format and size; it contains no file path. `media attach VM_REF --device ID --asset ASSET_ID --asset-revision REV --readonly|--writable --revision N` works for explicit local and remote targets. Choose exactly one access mode. The VM must be stopped; CDs must be read-only. The node checks original root/VM/manifest/file identity and the selected asset revision again under the media transaction lock. Assets from another VM, aliases, removed/missing/replaced files or changed selections fail. This does not register or upload arbitrary external files, share another VM's disk, authorize physical disks. Native/Web storage settings use the same catalog and task recovery.

Registered-node networking uses the ordinary `network nic add/update/remove VM_REF` and `network forward add/update/remove VM_REF` commands. Read `config resources VM_REF` first: `interfaces` includes stable legacy migration IDs, and `networks` contains this root's saved named-network IDs/types/revisions. Add/update reads `--file CLIENT_JSON`; all edits require `--revision N`, existing objects use `--nic NIC_ID`, forward removal also uses `--rule RULE_ID`. A named-network NIC requires its current `--network-revision N`. New NIC/rule IDs are assigned at the execution node. Changes are stopped-VM transactions; they do not install drivers, prepare a bridge, change the host IP/firewall or provide backend-readiness proof. Explicit `--allow-lan` confirms only the exact submitted LAN forwarding change and cannot replace any required prepared host authorization. On an uncertain result query the original full request reference; do not replay a prepared network transaction under another ID. `network show/nic list/forward list VM_REF` are read-only projections.

Syntax: `vm-cli.exe config resources <vm>`. This read-only command works for an explicitly selected local VM or, with registered-node management enabled, a full remote VM reference. It accepts the normal JSON/request/timeout options; `--root` can narrow a local selection and cannot redirect a remote target.

Returns `vm-cli-vm-resources/1`: complete target, configuration revision, target executable's hardware choice catalog, existing VM-scoped media references, and named networks in that target root. Public network entries contain ID/name/type/revision, with `backend_readiness: not-observed`. Host file paths, physical adapter identities, host preparation grants and credentials are excluded. `resources_revision` is a digest of this public snapshot, not authority to mutate it or evidence that a driver/network is ready. Re-read after a configuration/network change. Resource lookup never creates a disk, registers media, prepares a host bridge or starts a VM. Native/Web settings use the execution node's choices and fail explicitly if those resources cannot be read; they do not substitute client-side choices.

### config validate — Validate structure and hardware combinations

Syntax: `vm-cli.exe config validate <vm> [--file JSON]`. Validates saved configuration by default, or the optional candidate file. Returns valid/config_revision without writing configuration. Does not replace checks for media availability, host resources, or an actual guest boot.

Example: `.\vm-cli.exe config validate 'DOS Lab' --file '.\dos-config.json'`.

### config apply — Apply complete configuration

Syntax: `vm-cli.exe config apply <vm> --file JSON --revision N`. Both options are required. Cannot replace vm_id, preset origin, or the pinned firmware.bundle. Success increments the revision and returns the actual configuration. On CONFIG_CONFLICT, read the current configuration again and merge your changes instead of blindly overwriting it.

```powershell
$result = .\vm-cli.exe config show 'DOS Lab' | ConvertFrom-Json
$config = $result.data
$revision = $config.config_revision
$config.memory_mib = 64
$json = $config | ConvertTo-Json -Depth 20
[IO.File]::WriteAllText((Join-Path $PWD 'dos-config.json'), $json, [Text.UTF8Encoding]::new($false))
.\vm-cli.exe config validate 'DOS Lab' --file '.\dos-config.json'
.\vm-cli.exe config apply 'DOS Lab' --file '.\dos-config.json' --revision $revision
```

## device — Manage virtual peripherals

A device description is UTF-8 JSON with exactly four required fields: `id` (1–64 ASCII characters, starting with a letter, followed by letters/digits/underscores/hyphens), `kind`, `bus`, and `slot` (a zero-based integer). IDs and bus/slot pairs must be unique within a machine; at most 12 devices are allowed. Devices are distinct from media: adding cdrom creates an empty drive; media attach inserts an ISO. Manage CPU, network, display, and audio through config.

| Architecture/machine | kind | bus/slot |
| --- | --- | --- |
| x86 i440fx | disk/cdrom | ide 0–3; disks may also use virtio 0–7 |
| x86 Q35 | disk/cdrom | ide 0–5 (implemented as SATA); disks may also use virtio 0–7 |
| x86 i440fx | floppy | floppy 0–1; Q35 does not support floppy |
| ARM64 virt | disk | virtio 0–7 or scsi 0–7 |
| ARM64 virt | cdrom | scsi 0–7 |

Changes require a stopped VM and its current revision. Example device file: `{"id":"cd1","kind":"cdrom","bus":"ide","slot":3}`, saved as cd1.json. Use it only when that slot is available on the target machine.

### device list — List peripherals

Syntax: `vm-cli.exe device list <vm>`. The VM is required; no command-specific options. Example: `.\vm-cli.exe device list 'DOS Lab'`.

### device add — Add a peripheral

Syntax: `vm-cli.exe device add <vm> --file JSON --revision N`. Both options are required; file contains one complete device object as described above. Example: `.\vm-cli.exe device add 'DOS Lab' --file '.\cd1.json' --revision 1`. Returns the complete new configuration; use its new revision for subsequent media attachment.

### device update — Update an existing peripheral

Syntax: `vm-cli.exe device update <vm> --file JSON --revision N`. Both options are required. The JSON id identifies the existing device whose description will be replaced. Any retained media must still be compatible with the new device type. Example: `.\vm-cli.exe device update 'DOS Lab' --file '.\cd1.json' --revision 2`.

### device remove — Remove a peripheral

Syntax: `vm-cli.exe device remove <vm> --device ID --revision N`. Both options are required. Removes the hardware and its media reference, retaining disk/image files. Example: `.\vm-cli.exe device remove 'DOS Lab' --device cd1 --revision 3`.

## media — Attach, inspect, and eject media

Device IDs come from device list; revision is the current configuration revision. Attaching/ejecting hard disks requires a stopped VM. Only CD-ROMs and floppies support media changes while running, subject to control ownership. A writable image cannot be used by multiple VMs simultaneously. An ISO is raw CD-ROM media; an IMG is usually a raw floppy/disk image. Format is not inferred from the extension.

### media list — Inspect attached media

Syntax: `vm-cli.exe media list <vm>`. The VM is required. Returns media references indexed by device ID. Empty devices may be absent from this mapping; compare with device list. Example: `.\vm-cli.exe media list 'DOS Lab'`.

### media catalog — List this VM's retained disks

Syntax: `vm-cli media catalog VM_REF`. Lists retained product-owned disks of the selected local VM or remote VM. Local results contain the catalog array; remote results include the complete target and configuration revision with `retained_media`. `config resources VM_REF` exposes the same catalog. Entries contain `asset_id`, `asset_revision`, format, capacity, observed file bytes and creation time; no file path or file identity is returned. Reading creates no effect task and does not start the VM.

The catalog includes ejected disks retained by that VM. It does not list arbitrary host files, another VM's disks, external ISO registrations or physical devices. Missing/removed/replaced files and redirected registries fail explicitly; refresh after a changed selection. The revision binds the manifest and observed file identity/size, not an immutable disk-content hash. Use the asset attachment form below.

### media attach — Insert media into a device

Syntax: `vm-cli.exe media attach <vm> --device ID --path FILE --format raw|qcow2 --revision N [--readonly|--writable] [--session-id ID --epoch N]`.

Retained-disk form: `vm-cli media attach VM_REF --device ID --asset ASSET_ID --asset-revision REV --readonly|--writable --revision N`. Select the exact ID/revision from `media catalog VM_REF`, choose exactly one access mode, and stop the VM. This form works for local and remote targets and cannot be combined with `--path` or `--format`. IDE/SATA hard disks require writable access; CDs require read-only raw media. The node resolves its own same-VM retained manifest and rechecks file identity under the media lock. GUI/Web offer only compatible format/access choices. Unknown outcomes retain the original request reference; read that result instead of starting another attachment. Arbitrary external-media registration/upload is not supported through this asset form.

| Option | Default/requirement | Meaning |
| --- | --- | --- |
| `--device ID` | Required | Existing target device, e.g. cd0/floppy0/disk0 |
| `--path FILE` | Required | Existing regular host file; relative paths become absolute. Does not download files |
| `--format raw|qcow2` | Required | raw for ISO/floppy/raw disk; qcow2 must be standalone, with no external backing/data chain |
| `--revision N` | Required | Current configuration revision |
| `--readonly` | Read-only by default | Explicit read-only access; mutually exclusive with writable |
| `--writable` | Optional | Allow writes to the image. Required explicitly for IDE/SATA disks. CD-ROMs are always read-only and require raw; floppies also require raw |
| `--session-id ID --epoch N` | Optional; supply together | Use the current control session for a running VM; may be omitted when no session holds control |

Success returns the new configuration. IDE/SATA disks do not support read-only media; for a read-only disk, use a VirtIO device supporting it and verify guest driver support.

```powershell
.\vm-cli.exe media attach 'Linux Lab' --device cd0 --path 'E:\Media\linux.iso' --format raw --readonly --revision 1
.\vm-cli.exe media attach 'DOS Lab' --device floppy0 --path 'E:\Media\boot.img' --format raw --revision 1
.\vm-cli.exe media attach 'Empty DOS' --device disk0 --path 'E:\Disks\dos.qcow2' --format qcow2 --writable --revision 1
```

### media eject — Eject media while keeping the device

Syntax: `vm-cli.exe media eject <vm> --device ID --revision N [--session-id ID --epoch N]`. device/revision are required. Removes the media reference while retaining the CD-ROM/floppy/disk device and host file. Example: `.\vm-cli.exe media eject 'Linux Lab' --device cd0 --revision 2`.

## storage — Owned disks and cleanup

storage manages disks whose ownership vm-cli recorded in the current root. External files are not automatically claimed as deletable assets. Virtual disk capacity is not the same as current physical space usage.

### storage list — Inspect disk ownership

Syntax: `vm-cli.exe storage list`. No command-specific options. Reports asset IDs, ownership, paths, references, and related information. Use the returned asset identifier for cleanup. Example: `.\vm-cli.exe --root 'E:\VMs' storage list`.

### storage create — Create media for an empty disk device

Syntax: `vm-cli.exe storage create <vm> --device ID --disk-mib N --format raw|qcow2 --revision N`. All arguments are required. The VM must be stopped and the target must be a disk device with no media. N is 1–16777216 MiB. Creates a new internal file, attaches it writable, and returns the new configuration. Explicitly eject existing media first; this never overwrites an old disk.

Example: `.\vm-cli.exe storage create 'Empty DOS' --device disk0 --disk-mib 256 --format qcow2 --revision 1`.

### storage cleanup — Separately clean up a disk asset

Syntax: `vm-cli.exe storage cleanup --asset ID [--plan]`. asset is required and comes from storage list. plan is a no-value switch, off by default. First use plan to inspect ownership, references, and runtime use. Omit plan to actually delete an eligible disk file. Rejects referenced/in-use assets, files not owned by vm-cli, or an incomplete inspection of related directories. Deleting a VM does not automatically make its disks eligible for cleanup.

```powershell
.\vm-cli.exe storage cleanup --asset disk-ACTUAL_ID --plan
.\vm-cli.exe storage cleanup --asset disk-ACTUAL_ID
```

## firmware — Manage embedded firmware caches

Firmware bundles are pinned by SHA-256 and include BIOS, UEFI, and ROM resources. Caches are data files. Cleaning a cache does not delete a VM's writable UEFI state; applying configuration does not automatically select a different firmware bundle.

### firmware list — Inspect cached bundles

Syntax: `vm-cli.exe firmware list`. No command-specific options; applies to the current root. Returns bundle digests, resources, and references. Example: `.\vm-cli.exe firmware list`.

### firmware cleanup — Remove an unused bundle

Syntax: `vm-cli.exe firmware cleanup --bundle SHA256 [--plan]`. bundle is required: the 64-character lowercase hexadecimal digest returned by firmware list. plan defaults to off; when supplied, it only checks. Refuses deletion if instances or retained data reference the bundle, unknown files exist in the directory, or inspection is incomplete. Preview example: `.\vm-cli.exe firmware cleanup --bundle ACTUAL_64_CHARACTER_DIGEST --plan`. After reviewing, use the same command without `--plan` to delete.

## network — Manage network interfaces, named networks, and port forwarding

Use `network capabilities <vm>` before choosing a mode or adding a network card. A saved configuration is not proof of a working host backend. Inspect availability and reason codes: this build may reject bridge preparation, LAN exposure, or another unavailable backend with `NETWORK_HOST_PREPARATION_REQUIRED`, `NETWORK_BINDING_REQUIRED`, or `NETWORK_BACKEND_UNAVAILABLE`. It never substitutes independent NAT for a requested named network. The command interface does not claim that every backend has passed acceptance on Windows, macOS, and Linux.

| Mode | Intended connectivity | Configuration |
| --- | --- | --- |
| nat | Independent outgoing NAT for this card | Per-card private IPv4 /24; no named network |
| shared-nat | Cards on one network communicate and share an outgoing NAT gateway | Explicit named network in this data root |
| internal | Cards communicate; local DHCP/DNS, no product-provided default gateway or upstream DNS | Explicit named network in this data root |
| bridged | A prepared host adapter connects the card to the physical LAN | Explicit named network plus host preparation; LAN addressing applies |

The guest controls its own routes, services, firewall, and IP forwarding. An internal card does not isolate the whole VM when it has other cards; a guest may forward between them. Connecting a cable does not install a guest driver or verify internet access.

All operations use the selected `--root DIRECTORY`. Named networks are local to that root; the same display name in another root is a different network. References use returned `net-...` IDs. Host bindings and LAN permissions are host-local; copying a root does not authorize a new host.

VM schema 2 stores `network.interfaces`, including an empty array for zero cards. Each card has a stable `nic-...` ID and hardware `slot`; removing one does not renumber others. Capacity depends on the machine and occupied slots, not a fixed one-card limit. Reading schema 1 does not migrate it. The first explicit stopped network-topology mutation migrates it and persists identities and hardware positions. Schema 1 `off` represents a disabled card, not zero cards.

NIC, topology, and forwarding changes require a stopped VM. Only connect/disconnect can change one cable at runtime, subject to control ownership. In VM operations `--revision N` is `config_revision`. Named-network update/delete use the network's own `revision`; attaching a named network additionally requires `--network-revision N`.

Use one stable `--request-id ID` per mutation. After a lost reply, inspect `request show` and current state before replaying the same arguments/document. A revision conflict requires reading current state and preparing a new intentional change. Use `config show` for complete configuration edits: network query fields such as `effective`, `source_schema_version`, and `identity_persisted` are observations, not writable configuration.

### network capabilities — Inspect host support and available card slots

Syntax: `vm-cli.exe network capabilities [<vm>]`. Without a VM, returns backend availability and preparation reasons. With a VM, also returns hardware models, occupied/available slots, and remaining capacity. A slot is a hardware position, not an array index. Unavailable modes must not be silently replaced.

Example: `.\vm-cli.exe network capabilities 'Linux Lab'`.

### network adapters — List host network adapters

Syntax: `vm-cli.exe network adapters`. Returns adapter identities and addresses. Use actual IDs for host-specific operations. An adapter appearing here does not mean bridging is ready; Wi-Fi, VPNs, and host policy can restrict support.

Example: `.\vm-cli.exe network adapters`.

### network host inspect — Inspect local host preparation state

Syntax: `vm-cli.exe network host inspect`. Reads host identity, capabilities, and adapters without changing the host. Windows SeLow wired preparation/removal requires a matching installed service and an authorized Windows user. CLI, GUI and Web share the same ordinary-user service path; none implicitly installs or updates it. Other platforms retain their local preparation requirements. vm-cli does not automatically change firewall rules.

Example: `.\vm-cli.exe network host inspect`.

Preparation workflow: `network host prepare --mode bridged --network ID --adapter ADAPTER_ID --network-revision N --plan`, followed by `network host prepare --plan-id PLAN_ID --request-id ID`. Removal uses `network host remove --network ID --plan`, then `network host remove --plan-id PLAN_ID --request-id ID`. Keep the exact plan and request ID after an uncertain reply. Adapter IDs and unexpired plan IDs come from the current host. Unsupported adapters and missing service permissions remain explicit errors; Web does not bypass them.

Windows SeLow uses a shared, protected IPv4 LSO compatibility policy for the exact selected Ethernet adapter. If IPv4 LSO is enabled, the first preparation saves its original value, disables it and briefly reconnects the adapter so Windows sends frames the original driver can carry. Stop affected vm-cli bridge guests before that change. IPv6 LSO, checksum offload, IP addresses, configured routes, DNS and VPN configuration are not changed. Runtime host routes managed by a VPN can disappear or return on reconnect; complete snapshots are retained, and vm-cli does not rewrite those routes. Other grants reuse the policy. The final removal restores its recorded value and reconnects if needed; a service update retires idle grants and restores their adapter policies before the new build is prepared. A completed failed preparation attempts to restore its saved setting and returns the original error. A pending or conflicting native outcome is retained, not silently retried. CLI, GUI and Web display the same preparation/removal plan.

After a physical adapter reconnect, ordinary `network connect <vm> --nic <id> --revision <current>` can recover the same failed SeLow member without restarting the VM or changing its saved configuration. It confirms release of the original handle before reopening it; a failure remains visible and does not change other NICs. Host sleep/resume qualification is separately deferred.

Linux: use `./vm-cli` and inspect the selected host's plan. Native x64 and ARM64 qualification covers NetworkManager 1.46 Ethernet and eligible existing Linux bridges. The physical path coordinates addresses and routes with NetworkManager and restores the selected interface on removal. An uplink with externally managed routes, such as VPN-owned policy, is rejected before migration; arbitrary systemd-networkd migration is not claimed. CLI preparation uses the normal local sudo prompt; the native GUI uses PolicyKit. The privileged role is the same executable, while the frontend and VM engine remain ordinary-user processes. Web directs the user to local preparation and cannot accept a system password.

Linux bridge filtering and the host's existing forwarding policy can prevent DHCP or guest traffic even after a port is ready. vm-cli neither opens firewall rules nor stops VPN software. Have the host administrator resolve a concrete policy conflict before testing reachability; do not infer that a bridge or saved forwarding rule is reachable merely because its creation succeeded.

### network list — List named networks in the current root

Syntax: `vm-cli.exe network list`. Returns an array of network records with IDs, types, and revisions; there is no implicit cross-root joining.

Example: `.\vm-cli.exe --root 'E:\VMs' network list`.

### network create — Create a named network definition

Syntax: `vm-cli.exe network create --file JSON`. The UTF-8 file requires `name` and `type` (`shared-nat`, `internal`, or `bridged`). Name is 1–80 UTF-8 bytes without control characters. Independent NAT does not use this command.

For shared NAT/internal, omit `ipv4` to allocate a conflict-free private subnet, or provide the complete object. `cidr` is an RFC1918 network from /24 through /28; `dhcp_start`/`dhcp_end` are inclusive usable addresses. `dns` is a local service address outside the DHCP pool. Shared NAT requires a separate `gateway` outside the pool. Internal networks must omit `gateway`; bridged networks must omit `ipv4`, because the physical LAN supplies addressing.

Minimal `lab-network.json`:

```json
{"name":"Lab network","type":"shared-nat"}
```

Explicit internal-network example:

```json
{"name":"Private lab","type":"internal","ipv4":{"cidr":"10.45.0.0/24","dhcp_start":"10.45.0.20","dhcp_end":"10.45.0.200","dns":"10.45.0.3"}}
```

```powershell
.\vm-cli.exe network create --file '.\lab-network.json' --request-id lab-network-001
```

The result contains generated `network_id` and `revision`. Creating a definition does not grant bridge permission or prove its runtime backend is available.

### network inspect — Inspect a named network and effective state

Syntax: `vm-cli.exe network inspect <network-id>`. Returns the definition, members, host binding, and effective state. Read unavailable/inactive/unbound literally; none means a working bridge.

Example: `.\vm-cli.exe network inspect net-ACTUAL_ID`.

### network members — List cards referencing a named network

Syntax: `vm-cli.exe network members <network-id>`. Members identify both VM and NIC. One VM can have multiple cards on the same named network; each has an independent identity, MAC, and reservation.

Example: `.\vm-cli.exe network members net-ACTUAL_ID`.

### network update — Update a named network without changing its type

Syntax: `vm-cli.exe network update <network-id> --file JSON --revision N`. File requires the new `name` and optionally a complete `ipv4` object. Omitted IPv4 settings remain unchanged. Type and identity cannot change. Subnet changes require affected members stopped; conflicts with reservations, other networks, and host routes are checked. Active control ownership is respected.

Example: `.\vm-cli.exe network update net-ACTUAL_ID --file '.\lab-network-update.json' --revision 1 --request-id lab-network-update-001`.

### network delete — Delete an unreferenced named network

Syntax: `vm-cli.exe network delete <network-id> --revision N`. Refuses while any configured card references it, including disabled/disconnected cards. Reconfigure or remove the intended cards first; this command does not change member VMs.

Example: `.\vm-cli.exe network delete net-ACTUAL_ID --revision 2 --request-id lab-network-delete-001`.

### network show — Inspect cards and observed network state

Syntax: `vm-cli.exe network show <vm> [--nic ID]`. Returns all cards and current `config_revision`, or one exact card when selected. Schema 1 responses retain the original top-level mode/model/MAC fields and add normalized `interfaces`. Schema 2 uses the list as its authority. Querying does not migrate configuration.

Example: `.\vm-cli.exe network show 'Linux Lab'`.

### network nic list — List configured cards

Syntax: `vm-cli.exe network nic list <vm>`. Returns configuration revision and interfaces. Use returned IDs; never guess a NIC ID from its slot or array position.

Example: `.\vm-cli.exe network nic list 'Linux Lab'`.

### network nic add — Add a card while stopped

Syntax: `vm-cli.exe network nic add <vm> --file JSON --revision N [--network-revision N] [--allow-lan]`. File requires `mode` and `model`. Supported models come from `network capabilities <vm>`: currently rtl8139/e1000/virtio-net-pci for x86, virtio-net-pci for ARM64.

| NIC field | Meaning |
| --- | --- |
| id | Stable opaque identity; normally omit on add and use the generated value |
| slot | Stable available hardware position; omit on add to allocate |
| enabled | Boolean, default true; false removes the card from running hardware |
| mode | nat/shared-nat/internal/bridged |
| model | Guest-visible model; the guest needs its driver |
| mac | Lowercase nonzero unicast MAC; omit on add to generate a distinct one |
| link_state | connected/disconnected; new cards default disconnected |
| network_id | Required for named modes; forbidden for independent NAT |
| nat_cidr | Independent NAT only: RFC1918 /24; auto-selected when omitted |
| forwards | Rule array, default empty; maximum 64 across the whole VM |

Independent NAT cards must have different subnets and must not overlap the VM's named networks. The original first-card default remains 10.0.2.0/24; new cards allocate another available subnet. Multiple cards on the same named network are allowed. Hardware capacity determines whether another card fits.

Example `new-nic.json`:

```json
{"mode":"nat","model":"virtio-net-pci","link_state":"connected"}
```

```powershell
.\vm-cli.exe network nic add 'Linux Lab' --file '.\new-nic.json' --revision 3 --request-id lab-nic-add-001
```

For named modes include `network_id` and pass its current `--network-revision`. The result is the complete updated VM configuration.

### network nic update — Replace one card while stopped

Syntax: `vm-cli.exe network nic update <vm> --nic ID --file JSON --revision N [--network-revision N] [--allow-lan]`. Supply the complete selected card from `config show`, preserving ID, hardware slot, and forwarding rules. Editing another setting must not drop other cards or `pci_layout`. The result is the complete updated VM configuration.

Example: `.\vm-cli.exe network nic update 'Linux Lab' --nic nic-ACTUAL_ID --file '.\updated-nic.json' --revision 4 --request-id lab-nic-update-001`.

### network nic remove — Remove one card while stopped

Syntax: `vm-cli.exe network nic remove <vm> --nic ID --revision N`. Removes that card and its rules; other IDs/slots remain stable. Removing the final card produces zero cards. Does not delete a named network.

Example: `.\vm-cli.exe network nic remove 'Linux Lab' --nic nic-ACTUAL_ID --revision 5 --request-id lab-nic-remove-001`.

### network attach — Select a card's network mode while stopped

Syntax: `vm-cli.exe network attach <vm> [--nic ID] --mode nat|shared-nat|internal|bridged --revision N [--network ID --network-revision N] [--nat-cidr CIDR]`. Named modes require `--network` and its revision. Independent NAT accepts only `--nat-cidr`. Attach enables the card. Incompatible existing forwarding rules fail validation; they are not silently deleted.

For attach, cable operations, and forwarding writes, `--nic` can be omitted only with exactly one configured card. Multiple cards return `NIC_REQUIRED`; zero cards return `NIC_NOT_FOUND`.

```powershell
.\vm-cli.exe network attach 'Linux Lab' --nic nic-ACTUAL_ID --mode shared-nat --network net-ACTUAL_ID --network-revision 1 --revision 6 --request-id lab-attach-001
```

### network connect — Connect one virtual cable

Syntax: `vm-cli.exe network connect <vm> [--nic ID] --revision N [--session-id ID --epoch N]`. Works stopped/running, respecting control ownership. Preserves mode, network, hardware, and other cards. A disabled card returns `NIC_DISABLED`; enable it through a stopped configuration change first. Success does not prove guest internet access.

Example: `.\vm-cli.exe network connect 'Linux Lab' --nic nic-ACTUAL_ID --revision 7 --request-id lab-connect-001`.

### network disconnect — Disconnect one virtual cable

Syntax: `vm-cli.exe network disconnect <vm> [--nic ID] --revision N [--session-id ID --epoch N]`. Other rules match connect. Retains the card, membership, and saved rules; the disconnected card must not remain exposed through forwarding.

Example: `.\vm-cli.exe network disconnect 'Linux Lab' --nic nic-ACTUAL_ID --revision 8 --request-id lab-disconnect-001`.

### network forward list — Inspect forwarding rules

Syntax: `vm-cli.exe network forward list <vm> [--nic ID]`. Without a card selector, lists all VM rules with their `nic_id`; with it, lists that card's rules. A configured rule is not proof of an active/reachable listener.

Example: `.\vm-cli.exe network forward list 'Linux Lab'`.

### network forward add — Add a rule while stopped

Syntax: `vm-cli.exe network forward add <vm> [--nic ID] --file JSON --revision N [--allow-lan]`. Only independent/shared NAT accepts forwarding. Supports TCP/UDP IPv4, not IPv6 or wildcard listeners. IDs are VM-wide; the limit is 64 total rules, not 64 per card.

| Rule field | Meaning |
| --- | --- |
| name | Required, 1–80 UTF-8 bytes without control characters |
| protocol | Required tcp or udp |
| host_address | Defaults 127.0.0.1 on add; otherwise an exact local LAN IPv4 |
| host_port | Required integer 1–65535 on the host |
| guest_port | Required integer 1–65535 in the guest |
| enabled | Required Boolean; false saves a disabled rule |
| host_adapter_id | Required for LAN exposure; actual ID from network adapters |
| guest_ipv4 | Optional, only the selected card's allocated address; never an arbitrary destination |
| nic_id | Filled from the selected card on add; if supplied, must match |
| rule_id | Generated fwd-... identity; omit on add, retain on update |

Loopback is the default: other LAN computers cannot use a listener at 127.0.0.1. LAN exposure requires an exact adapter/address, explicit `--allow-lan`, and a ready host authorization backend. Wildcards such as 0.0.0.0 are rejected. Firewall rules are not opened automatically.

Example `ssh-forward.json`:

```json
{"name":"Guest SSH","protocol":"tcp","host_address":"127.0.0.1","host_port":2222,"guest_port":22,"enabled":true}
```

```powershell
.\vm-cli.exe network forward add 'Linux Lab' --nic nic-ACTUAL_ID --file '.\ssh-forward.json' --revision 9 --request-id lab-ssh-forward-001
```

The guest must run the service on its reserved address/port. Port collisions fail explicitly; vm-cli does not choose another host port silently.

### network forward update — Replace a rule while stopped

Syntax: `vm-cli.exe network forward update <vm> [--nic ID] --file JSON --revision N [--allow-lan]`. Supply the complete saved rule with unchanged `rule_id` and matching `nic_id`. Changed LAN exposure requires explicit confirmation. Do not copy observed/effective state into the document.

Example: `.\vm-cli.exe network forward update 'Linux Lab' --nic nic-ACTUAL_ID --file '.\updated-forward.json' --revision 10 --request-id lab-forward-update-001`.

### network forward remove — Remove one rule while stopped

Syntax: `vm-cli.exe network forward remove <vm> [--nic ID] --rule ID --revision N`. Use the actual `fwd-...` ID belonging to the selected card.

Example: `.\vm-cli.exe network forward remove 'Linux Lab' --nic nic-ACTUAL_ID --rule fwd-ACTUAL_ID --revision 11 --request-id lab-forward-remove-001`.

## screen — Observe the actual guest display

Requires a running VM. Queries and screenshots do not acquire control. All dimensions and coordinates refer to the original guest display, not the Viewer window or a resized screenshot.

### screen info — Inspect resolution and mouse capabilities

Syntax: `vm-cli.exe screen info <vm>`. The VM is required. Returns width/height, frame_id, runtime_id, cursor_composited, cursor_layer_supported, absolute_input, and relative_input. Example: `.\vm-cli.exe screen info 'DOS Lab'`.

### screen capture — Save a PNG screenshot

Syntax: `vm-cli.exe screen capture <vm> [--output PNG]`. output is optional and defaults to a unique filename in the instance's screenshots directory. A custom relative path is relative to this invocation's working directory. Existing files cause ALREADY_EXISTS and are never overwritten. Returns path and display information. Agents must actually open the image with an image tool before deciding that installation is complete, a menu appeared, or a click succeeded. Successful capture alone proves none of those outcomes.

```powershell
.\vm-cli.exe screen capture 'DOS Lab'
.\vm-cli.exe screen capture 'DOS Lab' --output '.\dos-screen-001.png'
```

## input — Send keyboard, mouse, and wheel events

Requires a running VM. One-shot keys, clicks, moves, and wheel events can be sent directly when no session holds control. Holding a key/button across commands requires control open first. When holding your own session, supply `--session-id ID --epoch N` on each command. Conflicting ownership returns CONTROL_BUSY; do not bypass human control. Default RPC timeout is 15000 ms.

A successful `submitted=true` means only that input was submitted; `guest_result_verified=false` explicitly does not guarantee guest completion. Observe a screenshot after significant actions. Do not automatically replay keys, clicks, or wheel events after a timeout or unknown outcome.

`--key` uses case-sensitive physical QEMU qcodes, with total length 1–64 bytes. Common names: Enter ret, Space spc, Backspace backspace, Tab tab, Escape esc, Delete delete, arrows left/right/up/down, Page Up/Down pgup/pgdn, Control ctrl, Alt alt, Shift shift, Windows meta_l. The guest keyboard layout interprets characters; arbitrary text is not a key code.

Complete qcode names (actual response still depends on device and guest support):

```text
unmapped shift shift_r alt alt_r ctrl ctrl_r menu esc
1 2 3 4 5 6 7 8 9 0 minus equal backspace tab
q w e r t y u i o p bracket_left bracket_right ret
a s d f g h j k l semicolon apostrophe grave_accent backslash
z x c v b n m comma dot slash asterisk spc caps_lock
f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
f13 f14 f15 f16 f17 f18 f19 f20 f21 f22 f23 f24
num_lock scroll_lock kp_divide kp_multiply kp_subtract kp_add
kp_enter kp_decimal sysrq kp_0 kp_1 kp_2 kp_3 kp_4 kp_5 kp_6 kp_7 kp_8 kp_9
less print home pgup pgdn end left up down right insert delete
stop again props undo front copy open paste find cut lf help
meta_l meta_r compose pause ro hiragana henkan yen muhenkan katakanahiragana
kp_comma kp_equals power sleep wake audionext audioprev audiostop audioplay
audiomute volumeup volumedown mediaselect mail calculator computer
ac_home ac_back ac_forward ac_refresh ac_bookmarks lang1 lang2
```

### input key — Press and release a key or chord

Syntax: `vm-cli.exe input key <vm> --key QCODE[+QCODE...] [--session-id ID --epoch N]`. key is required. Combine at most 8 distinct keys with plus signs. They are pressed and then released in reverse order. A chord cannot include a key already held down.

```powershell
.\vm-cli.exe input key 'DOS Lab' --key ret
.\vm-cli.exe input key 'DOS Lab' --key alt+f4
.\vm-cli.exe input key 'DOS Lab' --key ctrl+alt+delete
```

### input key-down — Hold one key

Syntax: `vm-cli.exe input key-down <vm> --key QCODE --session-id ID --epoch N`. key and an acquired control session are required. Use a single physical key, not a chord. Release with key-up or by releasing the session. Example: `.\vm-cli.exe input key-down 'DOS Lab' --key shift --session-id session-ACTUAL_ID --epoch 2`.

### input key-up — Release one key

Syntax: `vm-cli.exe input key-up <vm> --key QCODE --session-id ID --epoch N`. key and session arguments are required; use the same valid session that pressed the key. Example: `.\vm-cli.exe input key-up 'DOS Lab' --key shift --session-id session-ACTUAL_ID --epoch 2`.

### input move — Move the guest mouse

Syntax: `vm-cli.exe input move <vm> --x N --y N [--mode relative|absolute] [--session-id ID --epoch N]`. x/y are required signed decimal integers. mode defaults to relative; specify it explicitly and inspect screen info first.

relative applies to PS/2: x/y are horizontal/vertical deltas, each from -32767 to 32767; positive values move right/down. absolute applies to USB tablet: x/y are guest-display pixel coordinates from the top-left (0,0) to (width-1,height-1). A mode incompatible with configuration returns NOT_SUPPORTED. Query dimensions again after the guest resolution changes.

```powershell
.\vm-cli.exe input move 'DOS Lab' --mode relative --x 30 --y -15
.\vm-cli.exe input move 'Linux Lab' --mode absolute --x 320 --y 240
```

### input button — Click, hold, or release a mouse button

Syntax: `vm-cli.exe input button <vm> --button left|middle|right [--state click|down|up] [--session-id ID --epoch N]`. button is required. state defaults to click (one press and release). down/up require a valid session; moving while held performs a drag. Clicks use the current guest pointer position and do not take x/y.

```powershell
.\vm-cli.exe input button 'DOS Lab' --button left --state click
.\vm-cli.exe input button 'DOS Lab' --button left --state down --session-id session-ACTUAL_ID --epoch 2
.\vm-cli.exe input button 'DOS Lab' --button left --state up --session-id session-ACTUAL_ID --epoch 2
```

### input wheel — Scroll the mouse wheel

Syntax: `vm-cli.exe input wheel <vm> --steps N [--session-id ID --epoch N]`. steps is required: a nonzero integer from -100 to 100. Positive scrolls up, negative down; the guest application determines the actual scrolling. Example: `.\vm-cli.exe input wheel 'Linux Lab' --steps -3`.

## control — Maintain control across commands

A control session establishes exclusive ownership of input, live media changes, networking, and power changes for a VM. Read-only queries and screenshots remain available. The lease is 10000 milliseconds (10 seconds); renew it proactively. Exiting a CLI process does not immediately close its session. Expiry, close, human takeover, or hard reset releases held keys/buttons. Do not impersonate an sdl/web owner to bypass human control.

| Option | Meaning |
| --- | --- |
| `--owner-kind cli|sdl|web` | For open; defaults to cli. CLI agents should use cli; sdl/web belong to their respective Viewers |
| `--session-id ID` | session_id returned by open; used by renew/close and mutations while holding control |
| `--epoch N` | Current positive epoch returned by open/renew; supply with session-id. Never guess it or reuse an expired value |

Node-enabled builds also route an authorized remote VM reference through an ordinary-user role in the same executable. The role keeps the live encrypted control connection between short CLI commands; it does not elevate or install a system service. Keep both the returned session ID and epoch for held input, renew and close, and keep the complete VM reference. Each remote input needs its original request ID. A one-shot key, move, click or wheel request acquires and releases control; held keys/buttons require an explicit session. Unknown input must never be automatically resent: query its returned `node-ID/root-ID/input/REQUEST_ID` reference and observe the guest. A historical result cannot reopen a session after role restart. Client and role version/build IDs must match exactly. The Cloud account and installed build must support node management.

### control open — Acquire a control session

Syntax: `vm-cli.exe control open <vm> [--owner-kind cli|sdl|web]`. Returns session_id, epoch, and lease_ms. Another CLI or human session may cause CONTROL_BUSY. Example: `.\vm-cli.exe control open 'DOS Lab' --owner-kind cli`.

### control renew — Extend the same session

Syntax: `vm-cli.exe control renew <vm> --session-id ID --epoch N`. Both options are required. Extends a valid lease to 10 seconds. If expired, open a new session rather than reusing it. Example: `.\vm-cli.exe control renew 'DOS Lab' --session-id session-ACTUAL_ID --epoch 2`.

### control close — Release control and held input

Syntax: `vm-cli.exe control close <vm> --session-id ID --epoch N`. Both options are required. Releases this session and increments epoch without stopping the VM. Example: `.\vm-cli.exe control close 'DOS Lab' --session-id session-ACTUAL_ID --epoch 2`.

## view — Explicitly view one VM

Syntax: `vm-cli.exe view <vm> [--viewer sdl|web]`. The VM is required; viewer defaults to sdl. SDL opens a native window: SDL draws only the guest display, while management buttons are native system controls. Web requires a registered root; if disabled, it starts local-only Web access and returns a URL. Windows/macOS request that the system browser open it; other environments can use the returned URL. Never implicitly enables LAN access.

Viewing is read-only by default. A person acquires control through the keyboard/mouse control or takeover action. On Windows, the first click on the guest display only acquires control; F12, releasing control, or switching windows hands input back. Closing a Viewer does not stop the VM or recording. A Viewer does not replace start or install/boot the guest OS.

```powershell
.\vm-cli.exe view 'DOS Lab' --viewer sdl
.\vm-cli.exe view 'DOS Lab' --viewer web
```

## manager — Open the VM manager

Syntax: `vm-cli.exe manager`. No command-specific options. Explicitly opens/restores the local management interface for all of the current user's registered sources and VM states. Provides creation, viewing, machine/peripheral settings, data management, language, and light/dark appearance controls. The native UI supports 12 languages; CLI option names remain fixed and CLI help remains English. Closing the window normally retains the tray. Quitting the manager ends its process while VMs continue running. Example: `.\vm-cli.exe manager`.

Select a data source and VM before opening its **Settings**. Network adapters and port forwards are managed under **Network**; disks, device slots, file attachment and ejection are under **Storage & devices**. **Advanced configuration** edits a draft: validation and import do not apply it, and applying requires the displayed revision. Removing a device or deleting an instance keeps its disk files.

**Details** shows the selected VM's summary and read-only complete configuration/runtime results, including diagnostic reasons. **Storage → Clean up disks / Clean up firmware** lists resources by their actual identity. Open details or review a cleanup plan before confirming deletion of its exact path. Referenced resources remain inspectable but cannot be deleted; a changed plan must be reviewed again. **Registered Web media** shows file metadata and unregisters the selected entry without deleting its file or detaching it from existing VMs.

In **Cloud → Run**, **Choose destination networks** opens a per-adapter mapping for an already downloaded, verified package. Download the intended version first if no verified cache exists. Each source NIC keeps its identity; choose the destination network, or explicitly select independent NAT. Topology changes require an explicit choice. Saving pins the chosen package version and mapping and returns to the Run form; it does not start a VM. A separate Run submission starts the operation.

The Viewer's **Keyboard and mouse** controls use its explicit control lease. Losing control/focus or closing the input panel releases held input; submitting a form never silently reacquires control. The application tools retain original request IDs for uncertain results. Query or resume the original supported operation instead of opening a second mutation.

## tray — Open the tray or menu-bar entry

Syntax: `vm-cli.exe tray`. No command-specific options. Creates or reuses the current user's tray/menu-bar manager, listing registered directories, VM states, and SDL/Web viewing actions. The desktop must support the relevant tray mechanism. Quitting the tray does not stop VMs. Example: `.\vm-cli.exe tray`.

## root — Register and select VM data directories

The default directory and directories used by CLI create/start (including Cloud run) are registered automatically. Use root register to add other existing directories to the combined manager/Web interface. Registration does not copy VMs. Before moving a complete directory, stop its VMs/recordings and ensure no writes are in progress. A whole-directory copy is not a clone: two copies with the same root_id cannot be registered simultaneously as different sources.

### root list — List registered sources

Syntax: `vm-cli.exe root list`. Returns selected_root_id, paths, availability, and each directory's machines. Unavailable directories retain an error explanation; do not infer that they are empty. Example: `.\vm-cli.exe root list`.

### root register — Register a directory

Syntax: `vm-cli.exe root register <directory>`. directory is a required local path. First use may create the directory and its identity data. Does not automatically select the new directory. Example: `.\vm-cli.exe root register 'E:\VMs'`.

If `root list` reports `ROOT_IDENTITY_CHANGED`, keep the directory and its `root.json` intact. Explicitly registering the same directory can repair a stale management entry only when the existing disk-reference registry independently confirms the directory's current identity. The result includes `registration_repair` with the previous identity and repair time. CLI create/start never perform this repair implicitly. The native manager's Register directory action uses the same check. Repair does not rewrite VM identities, disks, network permissions or the reference registry. If the evidence disagrees or is missing, registration still fails: restore the original directory or collect the reported registered/observed identities for diagnosis. Do not delete registration files or regenerate `root.json` as a workaround. Missing registered directories remain unavailable and are not recreated by listing or re-registering them.

### root unregister — Unregister a directory

Syntax: `vm-cli.exe root unregister <directory-or-id>`. Required argument is a registered path or root_id; the default directory cannot be unregistered. Removes only the management entry, not the directory/VMs. Removing the selected directory selects the default again. Example: `.\vm-cli.exe root unregister 'E:\VMs'`.

### root select — Select the default operation directory

Syntax: `vm-cli.exe root select <directory-or-id>`. The target must be registered and available. Subsequent VM operations without root use this directory; explicit root still takes precedence. Example: `.\vm-cli.exe root select 'E:\VMs'`.

## web — HTTPS and LAN access

This is the current host user's shared Web service and displays only registered roots. It defaults to local-only listening. On first access to self-signed HTTPS, verify the certificate fingerprint. The program does not modify the firewall automatically; enabling LAN does not prove remote network reachability. Web passwords appear only in explicit credential responses, not URLs, ordinary status, or logs.

### web status — Inspect service status

Syntax: `vm-cli.exe web status`. No command-specific options. Returns enabled, state, available addresses, and related information, but not the password. Example: `.\vm-cli.exe web status`.

### web enable — Enable local or LAN access

Syntax: `vm-cli.exe web enable [--scope local|lan] [--port N]`. scope defaults to local (127.0.0.1); lan listens on all IPv4 interfaces. port defaults to 9443, range 1024–65535. First enable returns access URLs, a password, and the certificate fingerprint. An already enabled matching configuration reuses the service; explicitly use password show if needed. Disable first before changing scope/port.

```powershell
.\vm-cli.exe web enable
.\vm-cli.exe web disable
.\vm-cli.exe web enable --scope lan --port 9443
```

### web disable — Stop the Web service

Syntax: `vm-cli.exe web disable`. No command-specific options. Stops remote access without stopping VMs or recordings. Example: `.\vm-cli.exe web disable`.

### web password show — Reveal the access password

Syntax: `vm-cli.exe web password show`. No command-specific options. The current host user explicitly requests credentials. Output contains a sensitive password; show it only to people who need access. It can also be viewed/copied from the manager's Web access controls. Example: `.\vm-cli.exe web password show`.

### web password reset — Reset the access password

Syntax: `vm-cli.exe web password reset`. No command-specific options. Generates a new password and invalidates old browser sessions. VMs and recordings remain running. Example: `.\vm-cli.exe web password reset`.

## media-catalog — Register media for browser selection

The host media catalog supplies files for Web selection. Registering does not attach media; unregistering does not eject it. The browser does not expose arbitrary host file browsing. This catalog is distinct from a VM's media list.

### media-catalog list — List registered media

Syntax: `vm-cli.exe media-catalog list`. No command-specific options. Returns media IDs, paths, formats, and write policies. Example: `.\vm-cli.exe media-catalog list`.

### media-catalog register — Register local media

Syntax: `vm-cli.exe media-catalog register --path FILE --format raw|qcow2 [--writable]`. path/format are required and the file must exist. Defaults to read-only. writable is a no-value switch explicitly permitting remote writable use of this media; it does not change permissions on existing attachments automatically.

Example: `.\vm-cli.exe media-catalog register --path 'E:\Media\linux.iso' --format raw`.

### media-catalog unregister — Remove a catalog entry

Syntax: `vm-cli.exe media-catalog unregister <id>`. id is required and comes from list. Retains the file and existing attachments. Example: `.\vm-cli.exe media-catalog unregister media-ACTUAL_ID`.

## record — Record the guest display

Recording reads the VM display directly and works headless, independently of whether a Viewer is open. Output is H.264 MP4, currently without an audio track or host microphone capture. Guest resolution changes are scaled/letterboxed into a fixed canvas. One recording session per VM can run at a time.

### record start — Start recording

Syntax: `vm-cli.exe record start <vm> [--width N] [--height N] [--fps N] [--bitrate N] [--output MP4]`. Requires a running VM.

| Option | Default | Unit/range |
| --- | --- | --- |
| `--width N` | 1920 | Pixels, 64–3840; must be even |
| `--height N` | 1080 | Pixels, 64–2160; must be even |
| `--fps N` | 30 | Frames per second, integer 1–60 |
| `--bitrate N` | 6000000 | Bits per second, 100000–50000000, not KB/s |
| `--output MP4` | Instance recordings/record-ID.mp4 | Host output path; relative to the current working directory. Cannot overwrite an existing final or partial file |

Returns recording_id, state, output location, and settings. Save the ID for stop and inspect status to confirm the state. ALREADY_RECORDING means a session is already active. A fixed request-id can associate a recording start with the same settings, but this lives in recording state rather than request show's persisted operation records.

Example: `.\vm-cli.exe record start 'DOS Lab' --width 1280 --height 720 --fps 30 --bitrate 4000000 --output '.\demo.mp4'`.

### record status — Inspect recording state

Syntax: `vm-cli.exe record status <vm>`. No command-specific options. Returns the current/latest recording or idle. States include starting, recording, finalizing, completed, failed, and interrupted, with applicable paths or errors. Example: `.\vm-cli.exe record status 'DOS Lab'`.

### record stop — Stop and finalize a particular recording

Syntax: `vm-cli.exe record stop <vm> --recording-id ID`. ID is required and must identify the intended session. Does not stop the VM. If the returned state is still finalizing, keep checking status until completed before delivering the file. Example: `.\vm-cli.exe record stop 'DOS Lab' --recording-id record-ACTUAL_ID`.

During writing, the file uses `.partial.mp4`; successful finalization renames it to the final file. Written fragments may be recoverable after a crash/power loss, but complete playback is not guaranteed. Do not describe an incomplete file as a complete recording. Uses host media facilities and reports an explicit error if unavailable.

## login — Sign in to vm-cli Cloud

Syntax:

```text
vm-cli.exe login [--no-browser] [--wait|--no-wait] [--timeout MILLISECONDS]
vm-cli.exe login --resume <request-id> [--no-browser] [--wait|--no-wait] [--timeout MILLISECONDS]
vm-cli.exe login --cancel <request-id> [--timeout MILLISECONDS]
```

`login` creates a short-lived device authorization through AppBoss and returns a complete HTTPS activation link plus a short user code. The browser page requires the user to authenticate and explicitly approve the displayed device. The activation URL never contains an access token, refresh token, or the client's private claim proof. Do not ask the user to paste account passwords or returned session tokens into a terminal or chat.

An interactive terminal opens the activation link once and waits by default. A pipe, agent, SSH session, `--no-browser`, or `--no-wait` does not open a browser and returns a JSON result with `operation_state: pending`, `authorization_url`, `user_code`, `expires_at`, `poll_after_ms`, and `next_command`. No background process continues after the command returns. Use the exact local request ID in the returned `login --resume ...` command; it identifies the protected pending transaction, not an access token.

| Option | Meaning |
| --- | --- |
| `--no-browser` | Never open a browser. The complete activation URL remains in the JSON result for the user to open on this or another device |
| `--wait` | Poll only until approval, rejection, expiry, or this invocation's timeout. A timeout returns the still-pending transaction; it does not create another authorization |
| `--no-wait` | Persist the pending transaction and return immediately. Continue with `login --resume <request-id> --wait` |
| `--resume ID` | Continue the one locally protected pending transaction whose original request ID is `ID`. A lost create or acknowledge response is recovered without issuing a second usable session |
| `--cancel ID` | Cancel that pending transaction and remove its local proof. It cannot be combined with wait or browser options |
| `--timeout MILLISECONDS` | 1–300000; limits this invocation. The service's authorization expiry may be earlier |

On success, vm-cli stores only the native session for the current operating-system user: Windows uses current-user DPAPI, macOS uses the current user's Keychain, and Linux uses a private owner-only credential file in builds without a desktop secret-service adapter. CLI and GUI use the same protected account. Normal JSON output reports account identity and protection type but never prints access or refresh tokens.

```powershell
# Interactive desktop: opens the complete activation link and waits.
.\vm-cli.exe login

# Agent or remote shell: return the link without opening a browser.
.\vm-cli.exe --request-id login-lab-001 login --no-browser --no-wait
.\vm-cli.exe login --resume login-lab-001 --no-browser --wait --timeout 300000

# Explicitly cancel the still-pending transaction.
.\vm-cli.exe login --cancel login-lab-001
```

If `login` reports that the account is already signed in, it does not create another session. `AUTH_DENIED`, `AUTH_EXPIRED`, and `AUTH_CANCELED` are terminal for that transaction. `OUTCOME_UNKNOWN` includes the safe resume command; do not start a second login with a different request ID until the saved transaction is resolved or canceled.

## logout — Remove the local vm-cli Cloud session

Syntax: `vm-cli.exe logout`.

`logout` immediately removes the current user's local credentials and any pending device authorization, then attempts to revoke the remote native session. The JSON result distinguishes `remote_revocation: confirmed`, `not_required`, and `unconfirmed`. Local sign-out is effective even if the network is unavailable; for an unconfirmed remote revocation, use the account portal to inspect or revoke other sessions if required. Logout does not delete local VMs, Cloud caches, remote repositories, versions, or sessions on other devices.

```powershell
.\vm-cli.exe logout
```

## run — Create and start a new VM from an image

Syntax: `vm-cli.exe run --image SOURCE --on local --name NAME [--arch x86_64|aarch64] [--init-user NAME --ssh-public-key FILE] [--network-map JSON] [--root DIRECTORY] [--request-id ID] [--timeout MILLISECONDS] [--plan]`.

`--network-map JSON` maps portable named-network intent to networks in the selected local root. Schema 2 packages preserve zero/multiple cards and stable hardware positions but do not carry source MAC addresses, host port exposure, or host permissions. A zero-card package needs no mapping. Unlisted independent NAT cards keep their saved mode/slot/subnet; if a subnet conflicts, supply an explicit per-card override rather than silently replacing it. Every shared/internal/bridged source card requires an explicit mapping or returns `NETWORK_MAPPING_REQUIRED`.

The mapping file has `schema_version: 2`, `interfaces`, and optional Boolean `allow_topology_change` (default false). Each entry requires `source_nic_id` and `target_mode`. Named targets require actual `target_network_id` and positive `target_network_revision`; NAT targets may instead include `nat_cidr`. Duplicate/unknown source IDs are rejected. Cards on the same source logical network must keep a consistent target unless an explicit topology change is authorized. A mode change or split/merge must not be inferred from the presence of a mapping file. Retain the exact file with the original run request when retrying; mapping does not make an unavailable bridge ready.

Example mapping for one source card; use actual identifiers/revisions from the package and local `network list`:

```json
{"schema_version":2,"interfaces":[{"source_nic_id":"nic-SOURCE_ID","target_mode":"shared-nat","target_network_id":"net-LOCAL_ID","target_network_revision":1}]}
```

`--image` accepts a complete exported local image directory, `cloud://` or `official://`. Local paths belong to this caller. `--on local` explicitly selects execution on this computer; remote nodes and rented Cloud execution are not delivered in P1 and fail before creating a VM. `--plan` previews the verified configuration without creating or starting an instance; a missing Cloud cache returns `ready=false` and asks for `cloud pull`. For Cloud references, `run` first reuses a matching verified cache or performs the same authenticated resolution, compatibility checks, download, and SHA-256 verification as `cloud pull`. It reconstructs every declared asset into a new independent VM directory, verifies the exact embedded firmware revision, records immutable Cloud provenance without tokens, assigns a new local VM ID and locally administered unicast MAC address, and starts the VM headless. Cache objects are never used as writable qcow2 backing files.

| Option/argument | Meaning |
| --- | --- |
| `--image cloud://repository:selector` | Private repository slug plus required label, exact version ID, or `latest` |
| `--image official://system:selector` | Signed official system slug plus required label, exact version ID, or `latest` |
| `--on local` | Required execution location; image storage location does not select it |
| `--image DIRECTORY` | Complete `vm-cli-image-directory/1` package, not an arbitrary ISO or raw/QCOW2 file |
| `--name LOCAL-NAME` | Required local VM name, 1–200 UTF-8 bytes. It is never silently changed |
| `--arch` | Optional current-host assertion; it does not request cross-architecture emulation |
| `--init-user NAME` | First-start Linux account for an official server template supporting `nocloud-v1`. Requires `--ssh-public-key`. Use 1–32 lowercase letters/digits/underscore/hyphen, starting with a letter or underscore; system accounts such as root are rejected |
| `--ssh-public-key FILE` | One local OpenSSH Ed25519, RSA (2048+ bits), or ECDSA public-key file, at most 32 KiB. Requires `--init-user`. Private keys, multiple keys, authorized_keys options and arbitrary initialization scripts are rejected. The account and key are not uploaded to Cloud |
| `--root` | Data root receiving the independent VM and any required cache |
| `--request-id` | Durable run identity. Reuse the same ID and arguments after interruption; changed arguments return `REQUEST_CONFLICT` |
| `--timeout` | 1–86400000 ms; default 86400000 (24 hours) covering cache selection/download, reconstruction, and local startup. Download receives the remaining transfer budget; individual HTTPS calls and local startup remain bounded to at most five minutes |

A new request creates one new independent instance. If the requested name already exists in the destination root, return `INSTANCE_ALREADY_EXISTS` with its identity and use `start VM_REF`; neither the new syntax nor the transition spelling silently starts, overwrites or replaces it. Recovering the original request resolves its original journal first, keeps the pinned source and VM ID, and returns a completed receipt without restarting a VM that was subsequently shut down. Existing schema-1 run requests retain their recorded recovery protocol. A complete private cache or private local package can run offline. Official provenance retains the signed publication, freshness, withdrawal and snapshot-continuity checks before new creation; changing to a local path is not an exemption. Already-created VM startup remains independent of those new-instance gates.

Completion means the local VM process started. It returns `guest_readiness: unverified`; vm-cli does not claim that the guest finished booting or its applications are ready. The command never opens a Viewer. Use `screen capture`, input commands, `view`, or the manager when observation is required. Logging out later does not disable this local VM.

When both initialization options are supplied, vm-cli generates a local CIDATA ISO9660 data image inside the new VM directory and attaches it to the template's declared CD slot. It creates a new instance identity, disables password and direct root login, and gives the selected user sudo access through their SSH public key. No helper executable is extracted or invoked. The seed is a local instance asset and never enters the immutable official cache. Templates without NoCloud support and private restores reject these options. Without them, use the template's console first-boot flow; there is no shared default password.

Keep the original account and key when repeating the same request ID. Changed settings return `INITIALIZATION_CONFLICT` and cannot rewrite or initialize an existing VM again. An already-created VM is started with `start` and its saved settings, without first-start parameters. To initialize a separate VM with different settings, explicitly choose a new local name and request ID. `initialization_mode` distinguishes `nocloud-v1`, `console-first-boot`, and private restore; it does not mean the guest is ready. After the first boot, sign in with the matching private key through a network path you explicitly configured, or inspect the console to confirm initialization finished.

```powershell
.\vm-cli.exe login
.\vm-cli.exe --root 'E:\VMs' --request-id run-linux-001 run --image cloud://linux-lab:baseline --on local --name 'Restored Linux'

# Create from a signed official version and start it headless.
.\vm-cli.exe --root 'E:\VMs' --request-id run-official-ubuntu-001 run --image official://ubuntu-24-04-server-x64:latest --on local --name 'Ubuntu Server' --init-user vmuser --ssh-public-key "$env:USERPROFILE\.ssh\id_ed25519.pub"
.\vm-cli.exe --root 'E:\VMs' show 'Restored Linux'
.\vm-cli.exe --root 'E:\VMs' screen capture 'Restored Linux' --output '.\restored-linux.png'

# A retry reuses the same instance and never overwrites its changed disk.
.\vm-cli.exe --root 'E:\VMs' --request-id run-linux-001 run --image cloud://linux-lab:baseline --on local --name 'Restored Linux'
```

Windows, macOS, and Linux builds can fetch a missing private version over HTTPS. They can also create from a uniquely matching complete local cache and use `start VM_REF` to start an already-created local instance offline.

One transition release accepts the old positional Cloud-reference spelling and returns `warnings[].code=DEPRECATED_RUN_SYNTAX`. Do not mix positional sources with `--image`/`--on`. `cloud run` is not a second execution command.

## image — Export a complete local image

### image export — Export a stopped VM

Syntax: `vm-cli.exe image export VM_REF --output NEW_DIRECTORY [--plan] [--include-device ID]... [--eject-device ID]... [--request-id ID] [--timeout MS]`.

The time budget is 1–86400000 ms (default 24 hours), checked between capture blocks, validation reads and output objects. A single operating-system I/O call remains subject to the host. A timeout returns `OUTCOME_UNKNOWN`, records the original phase/error and leaves no finalized usable output; query or continue the same request rather than starting a replacement.

Require a normally stopped, non-writing source. Preview the source, included bytes, external media choices and target directory with `--plan`. Internal file media is included; external ordinary file media requires an explicit include/eject decision. Physical disks, USB devices, host grants and Cloud credentials are not captured. An existing output directory or output inside the source data root is refused. Export does not shut down the source automatically.

The output contains `image.json` and `objects/<prefix>/<sha256>` using container `vm-cli-image-directory/1` and the existing manifest/index formats. Lengths, SHA-256, exact closure, firmware, paths and disk layout are verified. A complete private package can run offline and produces independent writable files, a new VM ID and new MAC addresses. Source images are never writable backing files. This is a full stopped-instance export, not a live snapshot or a raw-disk copy operation.

Keep the original request ID, VM and output after interruption. The returned `request_ref` supports `request show REQUEST_REF`; replay resumes owned capture/staging and never overwrites a different output. Incomplete staging is not runnable. Native managers offer image export and local Image tasks under storage; viewing these local jobs does not read Cloud account credentials. Web selects a browser image directory for upload and downloads an export as ordinary ZIP64; extract it to obtain the same local directory format. Canceling or closing an unfinished browser upload stops that browser's sending; reselect the same directory with the same destination/name/options to continue its original upload and verified objects. Closing a page does not replace an already-started background task.

```powershell
.\vm-cli.exe image export VM_REF --output 'D:\Images\dev' --plan
.\vm-cli.exe image export VM_REF --output 'D:\Images\dev' --request-id export-dev-001
.\vm-cli.exe run --image 'D:\Images\dev' --on local --name dev-copy --request-id run-dev-copy-001
.\vm-cli.exe request show node-NODE/root-ROOT/export/export-dev-001
```

Use the actual complete request reference returned in JSON, rather than the illustrative placeholder above.

## node — Register computers and manage the node process

This command group requires the corresponding node directory, session, and WebRTC signaling features on vm-cli Cloud. A node registration authorizes selected data-root IDs; signing in alone does not register the computer. Keep this computer online with `node serve` to access its registered directories. vm-cli provides the same VM, image, Viewer and configuration operations in CLI, native manager and Web; availability depends on the current node, directory role and supported operation. No public Web listener is opened by node registration. Unsupported operations remain unavailable until implemented and qualified.

`run --image SOURCE --on NODE --name NAME [--root-id ROOT_ID] [--plan]` accepts a complete exported directory, `cloud://repository:selector`, or `official://system:selector`. Select the node's manager-authorized directory; multiple directories require an explicit root ID. `--root` is rejected for remote execution and never means a path on that node. Cloud bytes use this client's normal account and verified content cache; account credentials never enter the package or DataChannel. Architecture is chosen from the selected node, not this client's CPU. A required accelerator is checked on the execution node before reconstruction; downloading does not certify that accelerator as available.

A Cloud run pins the original resolved version in its normal pull journal before transfer. Retain source, node, root, name and request ID after interruption. Completed or unknown execution is read from the original node task, never replaced by another `latest` resolution. A missing completed source cache does not restart an already completed run. `--plan` can use an existing verified cache but does not download image bytes or admit a task; an uncached source returns `ready: false`. Official signatures, current signed trust snapshots and exact manifest/object closure remain required; the receiving node also validates official provenance through its normal account/trust path. First-start options and the graphical local-network editor remain local-only. An explicit `--network-map FILE` for the selected node is supported: its typed contents and network revisions are fixed in the original image task; the client filename is never sent to the node. The node performs normal mapping, topology, host preparation and commit checks. GUI and Web Run image use this same run command.

The remote route for `delete VM_REF` uses the current node root's manager permission. It has the same logical-removal semantics as local delete: the VM must be stopped, instance files are retained and external files are untouched. It does not accept purge, host paths or forced shutdown. The returned task receipt contains a deletion ID and retention policy, not host filesystem paths. After an unknown reply, query the original full `request_ref`; do not create another deletion request or rely on the VM disappearing from a list.

`screen info VM_REF` and `screen capture VM_REF [--output FILE]` read a currently running VM on its selected node with that root's screen/view permission. Capture transfers one frozen PNG over the authenticated channel, checks all chunks, the complete image and current authorization, then writes the file on this client. An explicit output must be new; without one, the file is in this client's private screenshots directory. It never treats the output as a path on the remote computer. Stopped, unavailable, moved or revoked targets fail explicitly; no VM is started and no partial screenshot is published. Closing the read connection leaves the VM running. This command is a read-only snapshot, separate from the continuous `view` window and its explicit input-control grant.

### node register — Register this computer with explicit directory roles

Syntax: `vm-cli node register --name NAME --grant ROOT_ID:ROLE [--grant ROOT_ID:ROLE ...] [--revision N] [--request-id ID]`.

First use `root list` to obtain the IDs of available, registered local data directories. Roles are `view`, `operator`, or `manager`; each root must be selected explicitly and cannot appear twice. Unknown roles and unavailable/unregistered roots are rejected. Only root IDs and roles are sent, not host paths. Normal account sign-in and this computer's separate protected node identity are required. Initial registration uses revision 0; changing or reactivating registration requires the current revision from `node show local`. Stop the ordinary-user node process and resolve pending control requests before changing its grants. A name does not replace the permanent node ID.

Save the request ID. After an unknown reply, repeat the identical command with that ID or query `node request register ID`; do not generate another registration. An old successful receipt is historical and does not reopen a revoked node. The result separately reports `enrollment_confirmed_current` and the current node state.

### node list — List this account's registered computers

Syntax: `vm-cli node list [--limit 1..100] [--cursor NODE_ID]`. Returns an owner-scoped page and, when more entries exist, `next_cursor`. It does not scan the LAN. Connection presence is separate from VM state and executable capabilities.

### node show — Inspect a registered computer

Syntax: `vm-cli node show NODE`. Use `local`, a complete node ID, or the exact current enrolled name. Revoked entries remain inspectable by full ID. Name lookup is bounded; if the directory cannot be resolved completely, use the complete ID instead of guessing a target.

### node unregister — Revoke a computer's remote registration

Syntax: `vm-cli node unregister NODE [--revision N] [--request-id ID]`. Without an explicit revision, the initial request reads and captures the current node revision. Retries keep the original complete target and revision even if a name is later reused. This revokes discovery and remote authority; it does not shut down VMs, delete disks, or sign out other devices. Control-plane revocation and the endpoint acknowledgment remain separate states.

### node request — Read the original directory result

Syntax: `vm-cli node request register|unregister REQUEST_ID`. Reads the existing account-scoped receipt without repeating the mutation. A returned historical result is not current execution authority.

### node serve — Run the ordinary-user node process

Syntax: `vm-cli node serve`. Runs in the foreground as the current host user after explicit registration. Keep the process running, press Ctrl+C to stop gracefully, or use `node stop` from another terminal. It uses the same executable and normal account credentials; it does not install a system service or request administrator access. Structured control-state events go to stderr, and the final command result goes to stdout. A lost reply is recovered using its exact saved control request before another action is attempted.

When the new WebRTC signaling API is enabled, the process negotiates direct connections with authorized clients. Cloud exchanges SDP and ICE candidates; VM commands, image chunks and frames travel over the direct DataChannel. STUN helps discover reachable addresses. If ICE cannot connect directly, the operation reports a connection failure rather than silently using a relay. Stopping the node process leaves VMs running.

The node accepts up to two simultaneous WebRTC connections. If busy, it returns a capacity error instead of queuing an operation indefinitely. Directory discovery, VM commands, images, screen viewing and input each check the selected directory role. The inventory-ready flag only describes discovery; inspect each returned operation result and the VM runtime separately. Stopping this process closes its connections and leaves VMs running.

The node and client retain the original requests for `start`, `shutdown`, `poweroff`, `reboot`, `reset` and revisioned `config apply`. The first selection captures the exact node, root, permanent VM ID and placement revision. Repeating the same request ID reads that saved target before resolving a name again, including after a client restart or normal re-login. Changing its operation, document or selected target returns `REQUEST_CONFLICT`.

`show VM_REF` and `config show VM_REF` read the selected node's complete settings and current public runtime observation using the root's read-only permission. Remote configuration documents explicitly identify their target and `node-scoped-media-references` view: attached files appear as `media_ref` values, never as paths on the observing computer. A read does not create a VM task or execute a pending action. Configuration validation follows the provider's architecture, so an x64 client can read ARM64 settings without claiming it can run them locally.

`config apply VM_REF --file FILE --revision N --request-id ID` requires the target root's manager permission. Use the scoped configuration document returned by `config show`, retain its target and revision, and edit its settings. Existing media references are resolved on that exact node; supplying a host path, command, different VM or media file identity is rejected. Use the selected VM’s retained-media catalog to reattach an existing disk. Arbitrary node paths and external-media upload are not supported by config apply. A repeat of the same original task never re-applies a completed or uncertain edit. If a node process was interrupted, only a matching completed local configuration receipt can settle the original outcome; it never repeats the write.

After a send attempt or lost reply, the client queries the original task over a fresh authorized connection. A missing remote task record is an unknown outcome, never permission to resubmit. Only a fresh authoritative `accepted` record can resume the same unattempted task. Historical task results include `request_ref` and `state_is_current=false`; they do not prove the VM's current power state. Use `view VM_REF --viewer sdl` or `--viewer web` to view the remote VM. Opening a Viewer does not start it or take input control. Explicit Take control or Send keys obtains control; releasing, losing focus or closing the Viewer releases input without stopping the VM. Direct ICE still requires a reachable network path; STUN success alone does not guarantee connectivity.

### node status — Inspect this computer's process and saved control state

Syntax: `vm-cli node status`. Checks the local process and displays saved session/pending-request metadata. It does not require a Cloud request. Cached session data is explicitly not current authority; use `node show local` for fresh control-plane presence.

### node stop — Request an ordinary-user node process to stop

Syntax: `vm-cli node stop`. If the process is running, requests graceful shutdown of its exact process instance and returns `stop_requested`; follow with `node status`. A stale stop request does not stop a later process instance. If a prior process has exited with an unresolved control request, continues that original request and closes its session using normal account authority. No VM is shut down or deleted.

## cloud — Transfer and manage Cloud versions

Cloud subcommands upload and download VM versions and manage the signed-in account, official catalog, repositories, quota, cache and transfer tasks. `cloud push` uploads; `cloud pull` downloads and verifies a local cache. Top-level `login` and `logout` manage authentication. Top-level `run` reconstructs and starts an independent VM at the selected `--on` location. The default is this computer; a registered computer is a separate destination. Rented Cloud compute is not provided. `cloud run` is not implemented. Top-level `push` and `pull` are not accepted; use `cloud push` and `cloud pull`. `cloud push --plan` performs preflight without uploading; a private `cloud push` without it performs the durable FOS/OSS transaction described above. These commands never make a private image public or scan arbitrary files outside the selected data root. Cloud business operations use the same JSON result envelope as other commands.

Cloud data belongs to the data root selected by `--root`. Complete cache records are stored under its private Cloud area and reference immutable, content-addressed objects by SHA-256 digest. `cloud cache list` rejects incomplete or unsafe metadata instead of presenting it as usable. `cloud cache remove` deletes one cache registration and only those object files that no other complete cache references. It never deletes a VM created from that cache.

### cloud push — Inspect and upload a stopped virtual machine

Syntax: `vm-cli.exe cloud push <vm-reference> <repository> [--version LABEL] [--plan] [--include-device ID]... [--eject-device ID]... [--template-init-device ID] [--root DIRECTORY] [--request-id ID] [--timeout MILLISECONDS]`.

`cloud push` packages a stopped VM for the signed-in account. A full `node-ID/vm-ID` can select another registered node: the node captures and uploads its own disks with its own normal login, which must belong to the same Cloud account. The selected directory requires a current manager grant. Host file paths and credentials are never sent by the client. `--plan` returns a path-free preflight; it does not upload or create a task. Native/Web forms pin the root and placement revision. Advanced clients can likewise supply both `--root-id ROOT` and `--placement-revision N` to reject a moved source.

For a remote upload, keep the exact `--request-id`, VM reference, repository, version and media selections. Read `request show NODE/ROOT/vm/REQUEST_ID` after uncertainty; an explicit repeat can continue only the original immutable capture. A read never resumes the upload. If no complete original capture exists, preserve the unknown result rather than recapturing changed data. A completed request returns the same Cloud task/version, not a second upload.

A private repository belongs to the signed-in account. A private repository is a lowercase slug such as `linux-lab`. An authorized official operator may instead use `official://<system>` with a required `--version` label. That path uploads to the isolated official storage namespace and creates an **unpublished administrator draft**. Upload permission never grants edit, publish, withdraw, or revoke permission, and this command never makes a system public. Private `--version` is optional; when omitted, the service assigns a unique immutable label. A label contains 1–64 ASCII letters, digits, dots, underscores, or hyphens and starts with a letter or digit; reserved selectors such as `latest` cannot be used as an official version label.

Run with `--plan` first. For a local source, planning is local-only: it locks the VM configuration long enough to verify a normally stopped state, resolves every attached medium, reports exact local paths and estimated bytes, and does not sign in, create a remote task, reserve storage, copy media, upload bytes, change the VM, or eject a local device. It also warns that guest accounts, keys, software, and personal files remain in selected disks; vm-cli does not automatically sanitize them.

| Option | Meaning |
| --- | --- |
| `--plan` | Return the complete capture scope, exclusions, required actions, firmware state, byte estimates, and ready flag without remote changes |
| `--version LABEL` | Requested immutable label. Required for `official://` drafts; optional for a private repository |
| `--include-device ID` | Explicitly authorize this external disk, CD-ROM, or floppy for the upload copy. Repeat for multiple devices. It does not move or modify the local source file |
| `--eject-device ID` | Remove an attached CD-ROM or floppy only from the upload copy. Repeat as needed. It never ejects the local VM's medium and cannot be combined with include for the same device |
| `--template-init-device ID` | Official operator uploads only: declare that this prepared guest supports NoCloud first-start account/SSH public-key initialization, using an existing CD-ROM device such as `cd0`. The device must be empty in the upload copy; explicitly add `--eject-device ID` if it has media. This declaration does not install cloud-init or sanitize the guest. Omit it unless that exact guest has been verified to support NoCloud |
| `--request-id ID` | Durable upload identity. Reuse the same ID after interruption; never generate a new ID merely because a request timed out |
| `--timeout` | 1–86400000 ms; default 86400000 (24 hours). It limits this foreground transfer and never powers off the VM or silently cancels an accepted Cloud task. Individual HTTPS calls remain bounded to at most five minutes |

Owned internal media is included automatically. External media is never uploaded by implication. An unresolved external hard disk requires `--include-device`; an external CD-ROM or floppy requires either explicit include or `--eject-device`. The VM must be genuinely stopped—`shutdown` only requests guest shutdown, so poll `show` until the state is `stopped`. qcow2 backing files and external data files are rejected rather than followed.

Without `--plan`, a ready upload creates an immutable local capture first. It reads each source twice under the stopped-instance locks, splits non-zero content into 8 MiB SHA-256 objects, records sparse zero ranges, validates the complete package, and never uploads local paths, host MAC addresses, AppBoss tokens, or raw lease credentials. It then creates or reuses a durable Cloud task and renews its fenced lease. Each object is uploaded through a short-lived FOS/OSS PUT authorization and verified by the service before the next object is authorized. This bounds unfinished provider uploads while preserving durable progress. Specified temporary storage-unavailable failures may be retried within the original command timeout; authorization, integrity and protocol failures are not silently retried. The service commits one immutable package only after verifying its complete object closure. A private target creates or reuses the private repository and returns its committed `version_id`. An official target requires the server-side `official.upload` permission, uses the service's fixed official storage owner, and returns `draft_id`, `version_id`, and `published: false`; an administrator must separately check, edit, and publish that draft. Repeating the exact command with the same `--request-id`, root, source, target, label, and media choices resumes the saved capture/task. A lost final response is recovered from the version or draft bound to that completed task; it does not create a duplicate.

```powershell
.\vm-cli.exe --root 'E:\VMs' cloud push 'Linux Lab' linux-lab --version baseline --plan
.\vm-cli.exe --root 'E:\VMs' cloud push 'Linux Lab' linux-lab --version baseline --include-device cd0 --plan
.\vm-cli.exe --root 'E:\VMs' cloud push 'Linux Lab' linux-lab --version baseline --eject-device cd0 --plan
.\vm-cli.exe --root 'E:\VMs' --request-id push-linux-baseline-001 cloud push 'Linux Lab' linux-lab --version baseline --timeout 300000
.\vm-cli.exe --root 'E:\VMs' cloud push 'Alpine Template' official://alpine-linux --version 3.22.1 --plan
.\vm-cli.exe --root 'E:\VMs' --request-id official-alpine-3-22-1 cloud push 'Alpine Template' official://alpine-linux --version 3.22.1 --timeout 300000
.\vm-cli.exe --root 'E:\VMs' cloud push 'Prepared Debian' official://debian-13-minimal --version 13-key-init --template-init-device cd0 --plan
.\vm-cli.exe --root 'E:\VMs' --request-id official-debian-13-key-init cloud push 'Prepared Debian' official://debian-13-minimal --version 13-key-init --template-init-device cd0
```

### cloud pull — Download and verify a private or official Cloud version

Syntax: `vm-cli.exe cloud pull <cloud://repository:selector|official://system:selector> [--arch x86_64|aarch64] [--root DIRECTORY] [--request-id ID] [--timeout MILLISECONDS]`.

For a node destination, add `--on NODE [--root-id ROOT_ID] [--plan]`. The default or `--on local` downloads to this computer. An enrolled node downloads directly with its own normal Cloud login for the same account; the caller's credentials and local root path are not forwarded. Select a manager-authorized root. `--root` is local storage only and cannot be combined with a remote destination. The node must support the selected architecture.

Choose a stable request ID. The node reuses its normal pull journal, pinned immutable version, object hashes and range checkpoints. A remote pull returns a `NODE_ID/ROOT_ID/cache/REQUEST_ID` reference. Use `request show REFERENCE` after an interrupted response; this query never starts a download. A later explicit invocation with the exact original arguments can continue an incomplete pull. Do not change source, architecture, node, root or request ID. A completed receipt describes the original cache publication, not current cache availability or guest readiness. It never creates or starts a VM. The normal pull lock prevents simultaneous work on that same download.

The remote invocation accepts a 1–300000 ms observation budget (default 90000); individual node download attempts remain bounded by the original connection admission. A timeout preserves verified progress and the request reference. `--plan` checks the source format and destination selection only and returns `ready=false`; it does not resolve a version, download bytes or certify source access. Native Download's **Download to** field and Web **Download to cache** choose the same destination. Their background transfer receipt survives closing the window.

`cloud pull` resolves either a repository belonging to the signed-in account or the separate trusted official catalog. `<selector>` is required and may be an immutable label, the exact `ver_...` version ID, or `latest`. The service fixes `latest` to one immutable active version before object transfer. `official://` additionally requires an active Weerocks LLC publication whose Ed25519 key is compiled into this vm-cli build; the signature binds the system, version, architecture, runtime profile, full canonical manifest and object closure. Unknown keys, invalid signatures, withdrawn/revoked live publications, and manifest mismatches fail closed. The command never accepts an HTTP URL, local path, public share, or another account's private namespace.

Before downloading large objects, vm-cli sends the actual host architecture, hardware-acceleration availability, supported package format, and relevant CPU features for server preflight. The client then independently validates the returned root manifest, guest architecture, execution policy, machine, firmware, devices, index-page coverage, object identity, object count, and stored-byte total. An incompatible package is rejected before the large transfer. This release has no architecture-bypass or archive-only switch.

Objects come directly from short-lived FOS/OSS HTTPS URLs, with up to four 8 MiB object transfers active at once. Each object is requested as strict 1 MiB byte ranges and the completed prefix is checkpointed under the selected data root. Repeating the exact cloud pull resumes at the next range after a network failure or process restart. AppBoss access tokens are sent only to `cloud.vm-cli.com`, never to object storage. vm-cli requires HTTP 206 and an exact `Content-Range`, bounds every response by the requested range, and rehashes the complete object with SHA-256 before it can enter the local content-addressed store. Each successful object in a concurrent batch is published immediately even when a sibling transfer fails, so an exact retry downloads only missing ranges and objects. An incomplete or corrupted object is never published; an invalid saved prefix is discarded and downloaded again, while links and special files are rejected. The complete cache directory becomes visible atomically only after the full immutable closure is present and verified.

| Option/argument | Meaning |
| --- | --- |
| `cloud://repository:selector` | Private repository slug plus required label, exact version ID, or `latest` |
| `official://system:selector` | Trusted official system slug plus required label, exact version ID, or `latest` |
| `--arch` | Optional assertion about the current host. It must equal this executable's host architecture; it does not request emulation or conversion |
| `--root` | Data root that receives the independent verified cache |
| `--request-id` | Stable operation identity. Supply one before the first attempt and reuse it after interruption so the locally fixed version and already verified objects are retained |
| `--timeout` | 1–86400000 ms; default 86400000 (24 hours). Expiry stops this invocation and preserves resumable local state; it does not publish an incomplete cache. Individual HTTPS calls remain bounded to at most five minutes |

`cloud pull` does not create a VM, start a guest, open the manager, or modify an existing VM. A successful result contains the original reference, immutable `resolved_reference`, and complete cache metadata. Use `cloud cache list` to inspect it. `LOGIN_REQUIRED` means run `login`; `INCOMPATIBLE_HOST` is a preflight rejection; `OBJECT_INTEGRITY_FAILED`, `PACKAGE_INVALID`, and `CLOUD_PROTOCOL_ERROR` must not be bypassed. Repeat an interrupted pull with the same root, reference, architecture, and request ID.

```powershell
.\vm-cli.exe login
.\vm-cli.exe --root 'E:\VMs' --request-id pull-linux-baseline-001 cloud pull cloud://linux-lab:baseline --timeout 300000
.\vm-cli.exe --root 'E:\VMs' cloud cache list

# Pin an exact immutable version instead of a label.
.\vm-cli.exe --root 'E:\VMs' --request-id pull-linux-exact-001 cloud pull cloud://linux-lab:ver_0123456789abcdef0123456789abcdef

# Pull a signed official publication. The product build must contain its trusted key.
.\vm-cli.exe --root 'E:\VMs' --request-id pull-official-alpine-001 cloud pull official://alpine-linux:latest
```

The authenticated HTTPS client and end-to-end pull path use WinHTTP on Windows, the system Foundation networking stack on macOS, and statically linked libcurl with the host CA trust store on Linux. All three enforce certificate and host verification, bounded timeouts, disabled redirects/cookies/implicit authentication, and bounded response bodies. Local VM and cache-management commands remain available offline.

### cloud account — Inspect the current Cloud account

Syntax: `vm-cli.exe cloud account [--timeout MILLISECONDS]`.

Returns the account identity established by the protected AppBoss session and vm-cli Cloud's current interpretation of that account: `app_id`, opaque `user_id`, `plan_id`, decimal-byte `quota_bytes`, `max_concurrent_transfers`, the monotonic entitlement revision, policy version, and observation time. It does not return access tokens, email addresses, payment details, VM contents, or object-storage credentials. It also does not reserve capacity or extend a transfer lease.

Use this command after login when an Agent must verify which Cloud account and policy it is about to use. `LOGIN_REQUIRED` means no usable local session exists. `ACCOUNT_POLICY_UNAVAILABLE` means the service refused to guess while AppBoss entitlement facts or durable account state were unavailable.

```powershell
.\vm-cli.exe login
.\vm-cli.exe cloud account
```

### cloud catalog — List active official systems

Syntax: `vm-cli.exe cloud catalog [--arch x86_64|aarch64] [--timeout MILLISECONDS]`.

Lists every official system with at least one active signed publication, following all service pages before returning one JSON result. Each item contains the stable system slug, display name, summary, available guest architectures, and last update time. `--arch` filters the returned systems to those with that exact guest architecture; it describes the guest image, not the host CPU, and does not translate or emulate another architecture.

The command returns metadata only. It does not download an image, create or start a VM, open a GUI, expose a draft, or make a private repository public. Withdrawn and revoked publications are absent from the consumer catalog. Catalog entries are curated vm-cli product data; AppBoss supplies the verified account session but does not host VM-specific catalog records or roles.

```powershell
.\vm-cli.exe cloud catalog
.\vm-cli.exe cloud catalog --arch aarch64
```

### cloud list — List all private repositories

Syntax: `vm-cli.exe cloud list [--timeout MILLISECONDS]`.

Lists every private repository owned by the signed-in account, following all service pages before returning one JSON result. Each repository includes its stable `repo_...` ID, URL-safe slug, display name, creation time, and revision. Use the stable repository ID with `cloud versions`; `cloud push` continues to accept the repository slug. Repository contents are private to the signed-in account and this command never lists another account or the official catalog.

`cloud list` is read-only. It does not download VM data, create a local cache, or open a GUI. `--timeout` covers the complete paginated request and defaults to 30000 milliseconds. A timeout does not change remote data.

```powershell
.\vm-cli.exe login
.\vm-cli.exe cloud list
```

### cloud repository — Create a private repository explicitly

Syntax: `vm-cli.exe cloud repository create <slug> --display-name <name> [--request-id ID] [--timeout MILLISECONDS]`.

`<slug>` is the private Cloud reference name: 1–63 lowercase ASCII letters, digits, or hyphens; it must start and end with a letter or digit. `--display-name` is the human-readable name and may contain spaces and Unicode text. Quote it in a shell. A slug is unique within the signed-in account.

Creation is idempotent by `--request-id`. Choose one stable request ID before the first attempt and reuse the same slug and display name after an uncertain response. Reusing that request ID with different content returns `IDEMPOTENCY_CONFLICT`; choosing a new request ID for an already existing slug returns `REPOSITORY_EXISTS`. `cloud push` may also create its target private repository when absent, so explicit creation is useful when the user wants to name or inspect the repository before uploading.

```powershell
.\vm-cli.exe --request-id create-linux-lab-001 cloud repository create linux-lab --display-name 'Linux Lab'
.\vm-cli.exe cloud list
```

### cloud versions — List active immutable versions in one repository

Syntax: `vm-cli.exe cloud versions <repository-id> [--timeout MILLISECONDS]`.

`<repository-id>` is the exact `repo_` identifier returned by `cloud list`, not a slug or `cloud://` reference. The command follows every page and returns active versions only. Each version includes its immutable `ver_...` ID, label, sequence, manifest digest, object and byte totals, creation time, state, and current revision. Preserve the returned revision when planning a delete or restore operation; stale revisions are rejected rather than overwriting a concurrent change.

Listing versions is read-only and transfers no VM object bytes. Versions moved to trash are intentionally absent; use `cloud trash` for them.

```powershell
$repositories = .\vm-cli.exe cloud list | ConvertFrom-Json
$repositoryId = $repositories.data.repositories[0].id
.\vm-cli.exe cloud versions $repositoryId
```

### cloud trash — List recoverable private versions

Syntax: `vm-cli.exe cloud trash [--timeout MILLISECONDS]`.

Lists all versions belonging to the signed-in account that are currently in the recoverable trash state. The result includes repository ID, version ID, revision, `trashed_at`, and `purge_after` when present. This query neither restores nor permanently removes anything. A trashed version continues to consume storage while its content remains retained.

```powershell
.\vm-cli.exe cloud trash
```

### cloud version — Plan, trash, restore, or permanently purge a version

Syntax:

```text
vm-cli.exe cloud version delete <version-id> --revision N [--plan] [--timeout MILLISECONDS]
vm-cli.exe cloud version restore <version-id> --revision N [--timeout MILLISECONDS]
vm-cli.exe cloud version purge <version-id> --revision N --plan [--timeout MILLISECONDS]
vm-cli.exe cloud version purge <version-id> --revision N --confirm permanent [--timeout MILLISECONDS]
```

These commands manage the **cloud version only**. They never delete or rewrite local VMs and never remove a local download cache. `<version-id>` and `--revision` must be copied from the latest `cloud versions` or `cloud trash` result. The service uses the revision and a fresh deletion plan to detect concurrent changes.

| Operation/option | Meaning |
| --- | --- |
| `delete` | Create a fresh trash plan and move one active version into recoverable trash. Shared content remains protected and retained content continues to count toward account usage |
| `delete ... --plan` | Return the fresh plan, including stored/shared/exclusively reclaimable bytes, recovery deadline, cleanup target and policy revision, without changing the version |
| `restore` | Restore one version from trash while its recovery window and required objects remain valid. Success returns the new version revision |
| `purge ... --plan` | Return the permanent-deletion impact and current revision without changing data. Review this immediately before permanent deletion |
| `purge ... --confirm permanent` | Permanently release the trashed version using a newly generated exact plan. The literal word `permanent` is required; `--confirm` without that value is rejected |

Normal deletion is recoverable. Permanent purge is intentionally unavailable for an active version: first move it to trash, inspect `cloud trash`, preview the permanent plan, and then issue explicit confirmation with the latest revision. Account used bytes decrease only after the last version or task reference is released and FOS confirms logical deletion. Physical storage cleanup happens asynchronously and does not delay the return of personal capacity after that confirmation. Shared objects remain charged and protected while another retained version references them.

`--plan` is read-only and always requests a current service plan. A final delete or purge obtains a fresh plan and saves that exact plan under the selected data root before changing Cloud state. Supply a stable `--request-id` for the final mutation. If its response is lost, repeat the exact command with the same root, request ID, version, revision, and operation; vm-cli reuses the saved plan and the service safely replays the result. Reusing that request ID with different lifecycle arguments returns `REQUEST_CONFLICT`. If the saved plan has expired or the version was changed by another client, inspect `cloud versions` and `cloud trash`, then reconsider the operation with a new request ID. Do not assume a local VM stopped working because its source Cloud version was deleted.

```powershell
# Move an active version to recoverable trash after reviewing its impact.
.\vm-cli.exe cloud version delete ver_0123456789abcdef0123456789abcdef --revision 1 --plan
.\vm-cli.exe --request-id trash-version-001 cloud version delete ver_0123456789abcdef0123456789abcdef --revision 1

# Restore with the revision returned by cloud trash.
.\vm-cli.exe cloud trash
.\vm-cli.exe --request-id restore-version-001 cloud version restore ver_0123456789abcdef0123456789abcdef --revision 2

# Permanent deletion requires a separate preview and literal confirmation.
.\vm-cli.exe cloud version purge ver_0123456789abcdef0123456789abcdef --revision 2 --plan
.\vm-cli.exe --request-id purge-version-001 cloud version purge ver_0123456789abcdef0123456789abcdef --revision 2 --confirm permanent
```

### cloud quota — Inspect authoritative capacity and transfer limits

Syntax:

```text
vm-cli.exe cloud quota [--timeout MILLISECONDS]
```

`cloud quota` signs in with the current protected Cloud session, refreshes the account entitlement, and reads the authoritative storage usage maintained by AppBoss FOS. It does not reserve storage, upload data, create a transfer task, or inspect the contents of a VM. Run it before a large `cloud push` when capacity or account-wide transfer concurrency may affect the operation.

The result contains the current `plan_id`; decimal-byte `quota_bytes`, `used_bytes`, `reserved_bytes`, `remaining_bytes`, and `overage_bytes`; stored and reserved object counts; active storage reservations; `max_concurrent_transfers`; policy, entitlement, and usage revisions; and observation timestamps. `reserved_bytes` represents capacity already held by unfinished operations, so free capacity is not `quota_bytes - used_bytes` alone. `remaining_bytes` is the service's calculated amount available after both used and reserved capacity. An overage is reported explicitly and never wraps around to a large unsigned value.

| Option | Meaning |
| --- | --- |
| `--timeout MILLISECONDS` | HTTPS request timeout from 1 to 300000 ms; default 30000 |
| `--request-id ID` | Optional request correlation ID. The query is read-only and does not create replay state |

`LOGIN_REQUIRED` means the local Cloud session is missing or expired. `USAGE_UNAVAILABLE` means the service could not obtain authoritative storage usage and therefore refused to guess. `RATE_LIMITED` includes `retry_after_seconds`; wait at least that many seconds and then repeat the exact operation instead of changing its request ID or assuming it completed. The limit applies across the account, including other clients and still-valid signed object authorizations.

```powershell
.\vm-cli.exe login
.\vm-cli.exe cloud quota
.\vm-cli.exe --timeout 60000 --request-id quota-check-001 cloud quota
```

### cloud task — List, inspect, cancel, or resume durable transfers

Syntax:

```text
vm-cli.exe cloud task list [--root DIRECTORY]
vm-cli.exe cloud task show <task-id> [--root DIRECTORY]
vm-cli.exe cloud task cancel <task-id> [--root DIRECTORY]
vm-cli.exe cloud task resume <task-id> [--root DIRECTORY] [--timeout MILLISECONDS]
```

`list` retrieves every page of transfer tasks owned by the signed-in account. `show` returns the current stage, revision, direction, repository, manifest, lease summary, and available state recorded by the service. Account isolation is enforced by the service; knowing another user's task ID grants no access.

`cancel` first reads the current revision and then requests cancellation with optimistic concurrency. It does not delete a successfully committed immutable version. A conflict means the task changed between the read and cancellation request; inspect it again before deciding whether cancellation is still appropriate.

`resume` locates the exact immutable upload capture under the selected local data root and continues it in the foreground. It never recaptures a changed source VM. If the capture was removed, the command returns `RESUME_DATA_MISSING`; repeat the original `cloud push` only if you intentionally want a new capture and task. Closing the terminal or reaching the timeout pauses local progress but is not cancellation.

`cloud task resume` uses the same 24-hour default and 1–86400000 ms range as `cloud push`. Omit `--timeout` for a long transfer; explicitly use a shorter value only when you want a bounded foreground attempt. Task list/show/cancel keep their existing five-minute maximum.

```powershell
.\vm-cli.exe cloud task list
.\vm-cli.exe cloud task show task_0123456789abcdef0123456789abcdef
.\vm-cli.exe cloud task resume task_0123456789abcdef0123456789abcdef --timeout 300000
.\vm-cli.exe cloud task cancel task_0123456789abcdef0123456789abcdef
```

### cloud cache — List, preview, and remove verified caches

Syntax:

```text
vm-cli.exe cloud cache list [--root DIRECTORY]
vm-cli.exe cloud cache remove <cache-id> [--plan] [--root DIRECTORY]
```

`<cache-id>` is the exact `cache_id` returned by `cloud cache list`. It has the form `cache_` followed by 32 lowercase hexadecimal characters. A cache record identifies its Cloud service, account subject, private repository, immutable version, guest architecture, selector, manifest digest, object count, and stored bytes. A `corrupt` entry is reported for diagnosis but cannot be removed through the normal verified-cache path; repair or replace its metadata and objects first.

| Operation/option | Meaning |
| --- | --- |
| `list` | Validate every local cache record and referenced object, then return `caches` and `count`. Missing objects, wrong sizes, symbolic links, invalid identifiers, unknown fields, duplicate digests, and incomplete records are reported as corrupt |
| `remove <cache-id>` | Atomically detach one complete cache, remove its exclusively referenced objects, retain objects shared by other complete caches, and return released object/byte counts |
| `--plan` | Calculate `exclusive_objects`, `exclusive_bytes`, and `shared_objects` without changing files. Use this before cleanup when a human wants to review the impact |
| `--root DIRECTORY` | Select the VM data root whose Cloud cache is inspected or changed |

Removal writes a durable local intent before moving the cache out of the active index. Repeating the same remove command after interruption resumes cleanup; repeating it after completion returns the saved completion result with `replayed: true`. Once a removal record exists, `--plan` returns `NOT_FOUND` because that cache is no longer active. Cleanup never follows symbolic links and fails closed on malformed cache or removal records.

```powershell
.\vm-cli.exe cloud cache list
.\vm-cli.exe --root 'E:\VMs' cloud cache list
.\vm-cli.exe cloud cache remove cache_0123456789abcdef0123456789abcdef --plan
.\vm-cli.exe cloud cache remove cache_0123456789abcdef0123456789abcdef
# Safe retry after a terminal, machine, or process interruption:
.\vm-cli.exe cloud cache remove cache_0123456789abcdef0123456789abcdef
```

## request — Resolve uncertain persisted operation results

Operations with persisted request records in the root include create/start/delete, config apply, device add/update/remove, media attach/eject, storage create, pull, run, and final Cloud version delete/purge. Generate and save a request-id before the first invocation. The same ID and arguments can retrieve or safely continue the original result without performing the operation twice. The same ID with different arguments/config-file contents returns REQUEST_CONFLICT. Pull/run and Cloud version lifecycle operations keep dedicated durable records under the selected root; `request show` currently reads only the general VM-operation journal. Cloud restore is replay-safe at the service when repeated with the same version and original revision, but does not create a local `request show` entry. Do not assume the same replay guarantee for input, shutdown, networking, or other operations.

### request list — Find original node tasks recorded by this client

Syntax: `vm-cli request list --source nodes [--cursor CURSOR]`. This owner-scoped page uses the current normal Cloud sign-in and has a fixed 15-second budget. It lists only public task references, complete VM targets and the last locally recorded status, never configuration documents or host paths. Continue with the returned opaque `next_cursor` until `complete` is true. It does not require the VM to remain listed and does not rerun any operation. It is not a server-wide audit log or a current VM status query; `request show REQUEST_REF` reads the original node result under current node/root permissions. Do not add `--root` or substitute another account's cursor.

The native manager exposes this list under **Cloud → Node tasks**. Web exposes **Node tasks** beside its data sources. Both can check an original result even when its VM has been removed from the manager. Checking may update this client's existing receipt cache and acknowledge its own pending form reference; it never creates a replacement VM task.

### request show — Inspect an original request

Syntax: `vm-cli.exe request show <request-id>`. Required argument: 1–100 ASCII letters, digits, underscores, or hyphens. Use the original operation's root. Returns persisted state, vm_id, and result; some pending/unknown requests are reconciled with current state. The record may not exist; ordinary status queries do not create a record for every command.

The remote lifecycle adapter returns a full reference in the form `node-ID/root-ID/vm/REQUEST_ID`. Use `vm-cli request show REQUEST_REF` with the current normal account to inspect that exact original result; do not add `--root`. This read-only lookup requires current access to that node and root, does not execute an accepted task, and can be used from another authorized client without its original local journal. A historical receipt is not a fresh authorization or current VM state. Public availability still depends on the registered-node release gate described above.

```powershell
.\vm-cli.exe --root 'E:\VMs' --request-id install-linux-001 create 'Linux Lab' --preset modern-x64
.\vm-cli.exe --root 'E:\VMs' request show install-linux-001
.\vm-cli.exe --root 'E:\VMs' show 'Linux Lab'
```

## compatibility — Query historical guest compatibility evidence

This embedded catalog contains test records; it does not download installation packages or repair guests. A historical match does not certify the current executable, different media, or all configurations. Preserve current_build_verified=false in your interpretation of the result.

| Option | Default/meaning |
| --- | --- |
| `--guest ID` | Optional for list; required for query. Use the exact guest.id from returned records |
| `--host-platform PLATFORM` | Current build platform by default; windows-x64/linux-x64/linux-arm64/macos-arm64 |
| `--host-version VERSION` | Optional for query, but omission prevents an exact match. Use the record's or actual host's version string |
| `--file CONFIG` | Required for query; complete UTF-8 configuration object without the result envelope |

### compatibility list — List historical records

Syntax: `vm-cli.exe compatibility list [--guest ID] [--host-platform PLATFORM]`. Returns evidence_catalog, records, and their scope. Example: `.\vm-cli.exe compatibility list --host-platform windows-x64`.

### compatibility show — Inspect one evidence record

Syntax: `vm-cli.exe compatibility show <record-id>`. ID is required and comes from list's records[].id. Returns the record as stored. Example: `.\vm-cli.exe compatibility show ACTUAL_RECORD_ID`.

### compatibility query — Compare a candidate configuration

Syntax: `vm-cli.exe compatibility query --guest ID --file CONFIG [--host-platform PLATFORM] [--host-version VERSION]`. guest/file are required. Compares hardware, firmware, media format/read-only settings, and related fields, not local filenames or VM identity. No match returns unverified; a historical match returns historical_evidence_found. Neither certifies the current build comprehensively.

Example: `.\vm-cli.exe compatibility query --guest ACTUAL_GUEST_ID --file '.\dos-config.json' --host-platform windows-x64 --host-version ACTUAL_HOST_VERSION`.

## configuration — Complete configuration-file fields

Call config show, then extract `data` into a UTF-8 JSON file. Do not redirect stdout unchanged into config apply: stdout contains a result envelope. Unknown fields, missing fields, and wrong types are rejected. Fields are required for their schema unless marked optional below. Preserve complete readback, including all cards and schema 2 hardware layout, when editing unrelated settings. apply preserves VM ID, preset origin, and firmware.bundle; the program increments config_revision on success.

| Field | Type, meaning, and constraints |
| --- | --- |
| schema_version | Integer 1 (legacy single card) or 2 (network.interfaces and persistent hardware layout); reads do not migrate, and schema 2 cannot be downgraded |
| vm_id | Stable identity from create; cannot be replaced by apply |
| name | Nonempty string, at most 200 UTF-8 bytes |
| config_revision | Current positive revision; also pass `--revision` for conflict detection |
| preset | Object with id and positive integer revision; original template source, cannot be replaced |
| guest_arch | String x86_64 or aarch64; must match this build |
| machine | x86: pc-i440fx-11.1/pc-q35-11.1; ARM64: virt-11.1 |
| cpu.model | x86: 486/pentium/pentium2/pentium3/qemu64/max; ARM64: max/cortex-a72 |
| cpu.count | Integer 1–64; 486/pentium require 1 |
| memory_mib | Integer MiB; x86 4–1048576, ARM64 128–1048576 |
| execution | software or required; required restricts CPU models and requires host acceleration |
| firmware.type | bios/uefi; x86 UEFI requires Q35; ARM64 requires UEFI |
| firmware.bundle | Pinned 64-character lowercase SHA-256 string; cannot be replaced by apply |
| boot_order | 1–3 unique characters: a floppy, c disk, d CD-ROM; ARM64 allows only c/d. Examples: dc, acd |
| display | x86: std/cirrus/virtio-vga; ARM64: virtio-gpu-pci; no guest 3D acceleration |
| input | x86: ps2/usb-tablet; ARM64: usb-tablet; determines relative/absolute input capabilities |
| network.mode | Schema 1 only: off/nat/disconnected; off has no enabled device, disconnected retains the device without a link |
| network.model | Schema 1 only: x86 rtl8139/e1000/virtio-net-pci; ARM64 virtio-net-pci |
| network.mac | Schema 1 optional explicit MAC; preserve when editing unrelated settings |
| network.interfaces | Schema 2 only: complete NIC objects, including [] for zero cards; fields and limits appear under network nic add |
| pci_layout | Schema 2 only: persistent hardware-role to slot mapping; preserve returned positions, never derive from array order |
| audio | x86: off/sb16/ac97/hda; ARM64: off/hda; playback only, no host microphone |
| serial | JSON boolean true/false; enables serial logging, not a guest shell command |
| devices | Array of at most 12 devices; each has id/kind/bus/slot, see device |
| media | Object indexed by device ID; `{}` for no media. Each entry has path/ownership/format/readonly |
| media.*.path | internal: relative path under the instance's disks directory; external: absolute path |
| media.*.ownership | internal or external; describes ownership, not permission to claim arbitrary external files for cleanup |
| media.*.format | raw/qcow2; CD-ROM/floppy require raw; qcow2 cannot have external dependency chains |
| media.*.readonly | Boolean; CD-ROM requires true, IDE/SATA disk requires false |
| cpu_timing | Optional, default standard; legacy-paced requires i440fx, one CPU, and software; not a MHz setting |
| ide_timing | Optional, default standard; win2000-install requires i440fx/software and an IDE disk; for troubleshooting legacy installation timing |

Writable UEFI variables are per-instance state files, not fields for callers to share manually through this table. Use compatibility to inspect legacy configurations, but do not infer that every installation problem is solved from a setting's name.

## results — JSON results, exit codes, and error handling

Business stdout is UTF-8 JSON; help is UTF-8 Markdown. Success exits with 0 and failure with 2. Exit 0 and ok=true may still mean pending; use specific fields and actual observation to verify guest completion. Interactive setup prompts use stderr; results use stdout. Terminal text alone is not evidence of success.

| Field | Meaning |
| --- | --- |
| schema_version | Result format version; currently 1 |
| request_id | Correlation ID for this invocation; not every ID has a persisted request show record |
| ok | Whether the command successfully submitted/completed its own operation |
| operation_state | completed/pending/rejected/unknown; unknown means uncertain outcome, not confirmed failure |
| observed_at | UTC observation time as an RFC3339 string |
| data | Command-specific result, null on failure; structure differs by command |
| error | Null on success; failure object has code, message, details, and retry |
| error.retry | Currently explicit_only; does not authorize automatic replay of side effects |

The following illustrate structure; IDs, timestamps, and data are not live state from your machine:

```json
{"schema_version":1,"request_id":"list-example","ok":true,"operation_state":"completed","observed_at":"2026-10-01T00:00:00Z","data":[],"error":null}
```

```json
{"schema_version":1,"request_id":"edit-example","ok":false,"operation_state":"rejected","observed_at":"2026-10-01T00:00:00Z","data":null,"error":{"code":"CONFIG_CONFLICT","message":"Expected current --revision","details":{"current_revision":3},"retry":"explicit_only"}}
```

| Common error code | Meaning and next step |
| --- | --- |
| INVALID_ARGUMENT | Invalid syntax, option, type, or hardware combination; read the relevant command help |
| NOT_FOUND / ALREADY_EXISTS | Missing target or existing name/file; inspect list/show again, do not overwrite files |
| CONFIG_CONFLICT | Stale configuration revision; read config show again, merge, and use the new revision |
| REQUEST_CONFLICT | Same ID with different arguments/file contents; inspect the original request and use a new ID for a separate operation |
| OUTCOME_UNKNOWN | The action may have executed; inspect request show if recorded, show, or a screenshot before resending input |
| CONTROL_BUSY / OPERATION_BUSY | Human/another caller owns control or an operation; wait or observe instead of queueing replays |
| CONTROL_SESSION_REQUIRED / STALE_CONTROL_EPOCH | Missing or expired session; check the current owner, then open/renew correctly |
| REQUIRES_STOPPED | Stop the VM before changing hardware/disks; do not automatically force power off |
| ACCEL_UNAVAILABLE | Host acceleration unavailable; inspect doctor. Explicitly switch to software only when the task permits and the hardware supports it |
| NOT_SUPPORTED | Unsupported command/configuration, e.g. graceful reboot or an incompatible mouse mode |
| RESOURCE_MISSING / RESOURCE_CORRUPT | Missing media/firmware or failed integrity check; locate the resource rather than creating an empty replacement VM |
| ROOT_UNAVAILABLE / ROOT_IDENTITY_CHANGED / ROOT_IDENTITY_CONFLICT | Inspect root list and preserve root.json. Restore a missing original directory; explicit registration repairs only independently corroborated stale management metadata. Conflicting copies or reference identities require diagnosis, not metadata deletion. |
| IDENTITY_MISMATCH | Runtime record does not match the queried instance; inspect the actual process and root. Do not treat unknown as running or stopped |
| ALREADY_RECORDING / RECORDING_BUSY | Existing recording or finalization in progress; inspect the original session with record status |
| ROOT_NOT_REGISTERED / WEB_UNAVAILABLE | Web requires a registered directory or available service; inspect root register / web status |
| SETUP_SELECTION_REQUIRED / SETUP_CONFLICT | Agent omitted client selection or an existing Skill was modified; specify clients and preserve modifications |
| IO_ERROR / ACCESS_DENIED | Path, host permission, or I/O failure; inspect the relevant files and user permissions |

This table covers common cases, not every detail from error.message/details. Commands do not automatically retry side effects by default. Closing a Viewer, deleting VM registration, requesting shutdown, and cleaning disks have different consequences.

## workflow — Create, install, operate, and hand over a VM

This example installs a new x86 Linux VM. Replace the media path with an ISO you actually obtained for the target architecture. PowerShell examples check ok before reading data; do not copy nonexistent paths literally. For actual tasks, prefer the absolute executable path and root recorded in the Skill's installation.json.

```powershell
$exe = (Resolve-Path '.\vm-cli.exe').Path
$vmRoot = 'E:\VMs'
& $exe setup --clients codex --root $vmRoot
& $exe version
& $exe host inspect
& $exe capabilities
& $exe preset show modern-x64
$created = & $exe --root $vmRoot --request-id linux-lab-create-001 create 'Linux Lab' --preset modern-x64 --memory-mib 4096 --cpus 2 --disk-mib 32768 | ConvertFrom-Json
if (-not $created.ok) { throw $created.error.message }
$vm = $created.data.vm_id
$attached = & $exe --root $vmRoot media attach $vm --device cd0 --path 'E:\Media\linux.iso' --format raw --readonly --revision $created.data.config_revision | ConvertFrom-Json
if (-not $attached.ok) { throw $attached.error.message }
& $exe --root $vmRoot --request-id linux-lab-start-001 start $vm
& $exe --root $vmRoot show $vm
& $exe --root $vmRoot screen capture $vm --output '.\install-001.png'
```

Next, actually open the screenshot, observe the installer, and use input move/button/key as needed. Capture again after each significant step. If media is missing, inspect available local media, then search online and download from an appropriate source within the task's authorization; verify available hashes/signatures. Use the user's available licenses/accounts where needed. vm-cli does not itself search, download, or fill out installation wizards. Confirm that installation reaches the guest OS, and if needed verify disk persistence through a graceful reboot.

```powershell
& $exe --root $vmRoot screen info $vm
# Choose coordinates from the actual screenshot; these are examples only.
& $exe --root $vmRoot input move $vm --mode absolute --x 320 --y 240
& $exe --root $vmRoot input button $vm --button left
& $exe --root $vmRoot input key $vm --key ret
& $exe --root $vmRoot screen capture $vm --output '.\install-002.png'
# Open a Viewer when the user explicitly asks to see the guest display.
& $exe --root $vmRoot view $vm --viewer sdl
```

Drag example: execute within the 10-second lease, renewing during longer operations. Coordinates must still come from actual observation.

```powershell
$opened = & $exe --root $vmRoot control open $vm | ConvertFrom-Json
if (-not $opened.ok) { throw $opened.error.message }
$lease = $opened.data
try {
    & $exe --root $vmRoot input button $vm --button left --state down --session-id $lease.session_id --epoch $lease.epoch
    & $exe --root $vmRoot input move $vm --mode absolute --x 420 --y 340 --session-id $lease.session_id --epoch $lease.epoch
    & $exe --root $vmRoot input button $vm --button left --state up --session-id $lease.session_id --epoch $lease.epoch
} finally {
    & $exe --root $vmRoot control close $vm --session-id $lease.session_id --epoch $lease.epoch
}
```

After installation, eject the ISO, record the display, and request graceful shutdown. Read the current revision instead of reusing a value from before installation:

```powershell
$current = & $exe --root $vmRoot config show $vm | ConvertFrom-Json
if (-not $current.ok) { throw $current.error.message }
& $exe --root $vmRoot media eject $vm --device cd0 --revision $current.data.config_revision
$recording = & $exe --root $vmRoot record start $vm --width 1280 --height 720 --fps 30 | ConvertFrom-Json
if (-not $recording.ok) { throw $recording.error.message }
# Perform the actions to record, then stop using the returned recording_id.
& $exe --root $vmRoot record stop $vm --recording-id $recording.data.recording_id
& $exe --root $vmRoot record status $vm
& $exe --root $vmRoot shutdown $vm
& $exe --root $vmRoot show $vm
```

Deliver the complete video only when record status is completed, and confirm shutdown only when show reports stopped. If shutdown is ignored, exit through the guest OS or decide whether to poweroff according to the user's authorization. If the user wants to continue using the VM, leave it running and release control.

### Send special keys to the guest

Native and Web display windows provide **Send keys** with Ctrl+Alt+Del, Alt+F1–F12, Ctrl+Alt+F1–F12, Alt+Tab, Ctrl+Esc, Super/Windows and Print Screen. Selecting a shortcut does not send it until Send is pressed. The action obtains the same exclusive guest control used by CLI input, sends the chord once and releases it; another controller is never overridden. Use Keyboard and mouse for arbitrary QCODE combinations or held keys. These actions send directly to the guest, including combinations intercepted by the host or browser.
