Command-Line Interface

Everything QuantaBox does in the GUI is available from the terminal through the quantabox command. This chapter is a task-oriented introduction; for the exhaustive option list, see the CLI Reference.

The quantabox Command #

The CLI shares the same core and data directory as the desktop app, so VMs you create in one appear in the other. Get help at any time:

quantabox --help
quantabox <command> --help
quantabox --version

VMs can be referenced by name (case-insensitive) or by ID.

Managing Virtual Machines #

# List all VMs
quantabox list

# Create a VM (presets fill sensible defaults per OS)
quantabox create my-ubuntu --os ubuntu-2404-desktop
quantabox create work --os fedora-40 --cpus 4 --memory 8192 --disk 50 --encrypted

# Inspect a VM
quantabox info my-ubuntu

# Lifecycle
quantabox start my-ubuntu
quantabox pause my-ubuntu
quantabox resume my-ubuntu
quantabox stop my-ubuntu            # graceful
quantabox stop my-ubuntu --force    # force kill

# Clone and delete
quantabox clone my-ubuntu --name my-ubuntu-copy
quantabox delete my-ubuntu
quantabox delete my-ubuntu --delete-disks

The ISO Library #

quantabox iso browse                   # list the catalog
quantabox iso browse --category server # filter by category
quantabox iso search ubuntu            # search by keyword
quantabox iso download ubuntu-2404-desktop
quantabox iso list                     # downloaded ISOs

Categories: desktop, server, security, developer, minimal.

Snapshots #

quantabox snapshot create my-ubuntu before-update
quantabox snapshot list   my-ubuntu
quantabox snapshot restore my-ubuntu before-update
quantabox snapshot delete  my-ubuntu old-snapshot

Packaging (Export / Import) #

# Export a VM to a portable package
quantabox package export my-ubuntu my-ubuntu.tar
quantabox package export my-ubuntu my-ubuntu.tar --encrypted

# Import a package (gets a new ID and folder)
quantabox package import my-ubuntu.tar

System Status #

quantabox status

status reports the QuantaBox version, the detected hypervisor backend, your platform and architecture, the encryption suite (ML-KEM-768 + AES-256-GCM), the data directory, VM counts, and the detected QEMU version. It is the first command to run when something is not working.

Scripting Tips #

• Stable references: scripts are more robust using VM IDs than names, since names can change.
• Exit codes: commands return 0 on success and non-zero on failure, so you can chain them with && or check $? in scripts.
• Logging: set the RUST_LOG environment variable (e.g. RUST_LOG=info) for more verbose diagnostics.

Example: batch-create a lab

for n in web db cache; do
  quantabox create "lab-$n" --os debian-12 --cpus 2 --memory 2048 --disk 20 --encrypted
done
quantabox list

Next #

For every command, flag, and default, see the CLI Reference. For problems, see Troubleshooting.