CLI Reference
Complete reference for the quantabox command. For a task-oriented introduction, see the Command-Line Interface chapter of the manual.
Synopsis #
quantabox <command> [arguments] [options]
quantabox --help
quantabox --versionVMs may be referenced by name (case-insensitive) or ID. Commands return exit code 0 on success and non-zero on failure. Set RUST_LOG (e.g. RUST_LOG=info) for more verbose logging.
list #
List all virtual machines.
quantabox listPrints a table: ID (short), Name, CPUs, Memory, Disk, State, and Encrypted.
create #
Create a new virtual machine.
quantabox create <NAME> --os <OS_TYPE> [--cpus N] [--memory MB] [--disk GB] [--encrypted]| Argument / Option | Type | Default | Description |
|---|---|---|---|
<NAME> | string | -- | VM name (required). |
--os <OS_TYPE> | string | -- | OS type (required), e.g. ubuntu-2404-desktop, fedora-40, debian-12, kali-linux, arch, windows11. |
--cpus <N> | u32 | 2 | vCPU cores. |
--memory <MB> | u64 | 4096 | RAM in megabytes. |
--disk <GB> | u64 | 25 | Disk size in gigabytes. |
--encrypted | flag | off | Enable PQC disk encryption (ML-KEM-768 + AES-256-GCM). |
Examples
quantabox create my-ubuntu --os ubuntu-2404-desktop
quantabox create work --os fedora-40 --cpus 4 --memory 8192 --disk 50
quantabox create secure --os windows11 --encryptedstart / stop / pause / resume #
Control a VM's lifecycle.
quantabox start <NAME_OR_ID>
quantabox stop <NAME_OR_ID> [--force]
quantabox pause <NAME_OR_ID>
quantabox resume <NAME_OR_ID>| Option | Applies to | Description |
|---|---|---|
--force | stop | Force-kill instead of graceful shutdown. |
info #
Show a VM's configuration and state.
quantabox info <NAME_OR_ID>Displays name, ID, state, OS, CPUs, memory, disks (path/size/format), encryption, network adapters, USB, and shared folders.
clone #
Clone a VM (configuration and disks) under a new name.
quantabox clone <SOURCE> --name <NEW_NAME>| Argument / Option | Description |
|---|---|
<SOURCE> | Source VM name or ID. |
--name <NEW_NAME> | Name for the clone (required). |
delete #
Delete a VM.
quantabox delete <NAME_OR_ID> [--delete-disks]| Option | Description |
|---|---|
--delete-disks | Also remove the VM's disk images. |
snapshot #
Manage VM disk snapshots (QCOW2/QVD disks only).
quantabox snapshot create <VM> <NAME>
quantabox snapshot list <VM>
quantabox snapshot restore <VM> <NAME>
quantabox snapshot delete <VM> <NAME>| Subcommand | Description |
|---|---|
create | Create a snapshot named <NAME>. |
list | List snapshots (tag, size, date/time). |
restore | Roll the disk back to <NAME> (current changes are lost). |
delete | Remove snapshot <NAME>. |
iso #
Browse and download OS images from the built-in catalog.
quantabox iso browse [--category <CATEGORY>]
quantabox iso search <QUERY>
quantabox iso download <ID>
quantabox iso list| Subcommand | Argument / Option | Description |
|---|---|---|
browse | --category <CATEGORY> | List the catalog; optionally filter by desktop, server, security, developer, or minimal. |
search | <QUERY> | Search by name, description, or tag. |
download | <ID> | Download an image by its catalog ID. |
list | -- | List already-downloaded ISOs. |
package #
Export and import VM packages.
quantabox package export <VM> <OUTPUT> [--encrypted]
quantabox package import <PATH>| Subcommand | Argument / Option | Description |
|---|---|---|
export | <VM> <OUTPUT> | Export a VM to a package file (config.json + disks). |
export | --encrypted | Encrypt the package with post-quantum encryption. |
import | <PATH> | Import a package; the VM gets a new ID and folder. |
status #
Show system and engine information.
quantabox statusReports: QuantaBox version, detected hypervisor backend, platform and architecture, the encryption suite (ML-KEM-768 + AES-256-GCM), data directory, VM counts, and the detected QEMU version (or not found).
Global Options #
| Option | Description |
|---|---|
--help | Show help for the command. |
--version | Show the QuantaBox version. |
Environment #
| Variable | Effect |
|---|---|
RUST_LOG | Sets log verbosity (e.g. error, warn, info, debug). |
Data Directory #
| Platform | Default |
|---|---|
| Windows | %LOCALAPPDATA%\QuantaBox |
| Linux | ~/.local/share/quantabox |
| macOS | ~/Library/Application Support/QuantaBox |
VMs created with the CLI are visible in the desktop app and vice versa.