CLI Reference

QV-CLI-001 Rev 1.0 — January 2026

Complete command reference for the quantavirt CLI tool — managing VMs, storage, networks, PQC keys, and host configuration from the terminal.

CLI Overview #

The quantavirt CLI is a Rust binary that communicates with the hypervisor's management API over a local Unix socket or TCP connection. All commands follow the pattern:

quantavirt <resource> <action> [target] [options]

Global Options #

OptionShortDescription
--host <addr>-HConnect to remote hypervisor (default: unix:///var/run/quantavirt/api.sock)
--port <port>-PTCP port for remote connections (default: 9400)
--format <fmt>-fOutput format: table, json, yaml, csv (default: table)
--quiet-qSuppress non-essential output
--verbose-vIncrease verbosity (repeat for more: -vvv)
--version-VPrint version and exit
--help-hPrint help for any command

vm — Virtual Machines #

vm create

quantavirt vm create --config <path.json>
quantavirt vm create --name myvm --cpus 2 --memory 2G --disk web-server --network default

vm list

quantavirt vm list [--state <RUNNING|STOPPED|PAUSED|ALL>] [--format json]

vm show

quantavirt vm show <name>

Lifecycle Commands

CommandDescriptionFrom StateTo State
vm start <name>Boot VMCREATED / STOPPEDRUNNING
vm stop <name>Graceful ACPI shutdownRUNNINGSTOPPED
vm stop <name> --forceImmediate power-offRUNNING / PAUSEDSTOPPED
vm pause <name>Freeze all vCPUsRUNNINGPAUSED
vm resume <name>Unfreeze vCPUsPAUSEDRUNNING
vm reset <name>Hard reset (triple-fault)RUNNINGRUNNING
vm destroy <name>Delete VM (keeps disks)STOPPED—
vm destroy <name> --purgeDelete VM and all disksSTOPPED—

vm set

# Modify VM configuration (VM must be stopped unless hot-pluggable)
quantavirt vm set <name> --cpus 4
quantavirt vm set <name> --memory 8G
quantavirt vm set <name> --cpu-pin 0:4,1:5,2:6,3:7
quantavirt vm set <name> --cpu-weight 512
quantavirt vm set <name> --cpu-cap 50
quantavirt vm set <name> --description "Production web server"

vm console / vnc

# Attach to serial console
quantavirt vm console <name>
# Press Ctrl+] to detach

# Show VNC connection info
quantavirt vm vnc <name>
# VNC: 127.0.0.1:5900 (password: ****)

vm snapshot

quantavirt vm snapshot create <name> --name <snap-name> [--memory] [--description "..."]
quantavirt vm snapshot list <name>
quantavirt vm snapshot restore <name> --name <snap-name>
quantavirt vm snapshot delete <name> --name <snap-name>

vm clone

quantavirt vm clone <source> --name <new-name> [--full] [--linked]

vm migrate

quantavirt vm migrate <name> --dest <host:port> [--pqc] [--bandwidth 10G] [--timeout 300]

vm disk-attach / disk-detach

quantavirt vm disk-attach <name> --storage <disk-name> --controller virtio-blk
quantavirt vm disk-detach <name> --storage <disk-name>

vm attest

quantavirt vm attest <name> [--output report.json]

storage — Disk Images #

CommandDescription
storage create --name N --format F --size SCreate disk image (format: raw, qcow2, encrypted)
storage listList all disk images
storage info <name>Show disk image details
storage resize <name> --size SGrow disk image (no shrink)
storage convert <name> --target-format FConvert between formats
storage compact <name>Reclaim sparse QCOW2 space
storage check <name>Verify image integrity
storage rekey <name> --key KRotate encryption key
storage delete <name>Delete a disk image
storage pool-add --name N --type T ...Add storage pool (nfs, iscsi, ceph, local)
storage pool-listList storage pools
storage pool-remove <name>Remove storage pool

network — Virtual Networks #

CommandDescription
network create --name N --mode M ...Create virtual network (mode: nat, bridge, isolated, tunnel)
network listList all virtual networks
network show <name>Show network details and attached VMs
network delete <name>Delete a network (must have no VMs)
network set <name> --mtu NModify network settings
network forward <name> --protocol P ...Add port forwarding rule (NAT only)
network forward-list <name>List port forwarding rules
network forward-delete <name> --id IDelete port forwarding rule
network rule add <name> ...Add firewall rule
network rule list <name>List firewall rules
network rule delete <name> --id IDelete firewall rule
network dhcp-static <name> ...Add static DHCP reservation
network dhcp-list <name>List DHCP leases
network tunnel-status <name>Show PQC tunnel status

pqc — Cryptography #

CommandDescription
pqc statusShow PQC backend status (QUAC 100 or software)
pqc self-testRun all PQC algorithm self-tests
pqc benchmarkRun PQC performance benchmarks
pqc key-gen --algorithm A --name NGenerate ML-KEM or ML-DSA keypair
pqc key-listList all keys in key store
pqc key-export <name> --publicExport public key
pqc key-import --name N --input FImport a public key
pqc key-rotate <name>Rotate a key (re-encrypt dependents)
pqc key-delete <name>Delete a key from the key store
pqc verify-attestation --report F --pubkey KVerify an attestation report

system — Host Management #

CommandDescription
system showShow hypervisor host information (CPU, memory, version)
system cc-statusShow confidential computing capability (SEV/TDX)
system sriov enable --interface I --num-vfs NEnable SR-IOV VFs on physical NIC
system iommu-groupsList IOMMU groups and devices
system update-firmwareUpdate QUAC 100 firmware
system stats [--interval N]Live resource usage statistics
system config showShow active hypervisor configuration
system config set <key> <value>Change hypervisor setting (requires restart)

audit — Security Logging #

CommandDescription
audit list [--last <duration>]View audit events (e.g. --last 24h, --last 7d)
audit export --format F --output OExport audit log (json, csv, syslog)
audit followTail audit events in real-time

Output Formatting #

# Default table output
quantavirt vm list
# NAME        STATE     CPUS  MEMORY  UPTIME
# web-01      RUNNING   2     2 GiB   4d 3h
# db-01       RUNNING   8     32 GiB  4d 3h

# JSON output (for scripting)
quantavirt vm list --format json
# [{"name":"web-01","state":"RUNNING","cpus":2,...}]

# YAML output
quantavirt vm list --format yaml

# CSV output
quantavirt vm list --format csv

# Quiet mode (names only — useful with xargs)
quantavirt vm list --state RUNNING --quiet
# web-01
# db-01

# Example: stop all running VMs
quantavirt vm list --state RUNNING -q | xargs -I{} quantavirt vm stop {}

Shell Completions #

# Generate shell completions
quantavirt completions bash > /etc/bash_completion.d/quantavirt
quantavirt completions zsh > ~/.zfunc/_quantavirt
quantavirt completions fish > ~/.config/fish/completions/quantavirt.fish
← Previous: PQC & Security Next: Management API →