.TH MVM 1 "June 2026" "mvm 0.1.0" "User Commands"
.SH NAME
mvm \- MicroVM Manager - Container speed, VM isolation
.SH SYNOPSIS
.B mvm
[\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]...
.SH DESCRIPTION
.B mvm
is a production-grade CLI for managing microVMs on Linux.
It handles the full VM lifecycle: downloading kernels and images, setting up bridge networking,
creating and destroying VMs, SSH access, log streaming, snapshots, and cleanup.
.PP
The following CLI aliases are available:
.BR net
for
.BR network ,
.BR img
for
.BR image ,
.BR vol
for
.BR volume ,
.BR bin
for
.BR binary ,
.BR ss
for
.BR snapshot ,
.BR "env up"
for
.BR "env apply" ,
and
.BR "env down"
for
.BR "env destroy" .
.SH OPTIONS
.TP
.BR \-\-verbose
Enable verbose output.
.TP
.BR \-\-debug
Enable debug mode with detailed error messages and stack traces.
.TP
.BR \-\-version
Show the version and exit.
.TP
.BR \-\-help
Show this help message and exit.
.SH COMMANDS
.SS VM Management
.TP
.BR vm\ create
Create and start a new Firecracker VM.
.RS
.PP
.B \-\-image
OS image (e.g. ubuntu:24.04).
.PP
.B \-\-kernel
Kernel to use.
.PP
.B \-\-vcpu
Number of vCPUs (default: 1).
.PP
.B \-\-mem
Memory size (e.g. 2G, default: 512M).
.PP
.B \-\-disk-size
Root disk size (e.g. 20G).
.PP
.B \-\-network
Network to attach to.
.PP
.B \-\-count
Create multiple VMs atomically.
.PP
.B \-\-allow-remote-exec
Allow inter-VM remote execution via vsock relay (default: disabled).
.RE
.TP
.BR vm\ rm
Stop and remove VMs by short ID or name.
.TP
.BR vm\ ls
List running and stopped VMs.
.TP
.BR vm\ ps
List running VMs (active processes).
.TP
.BR vm\ inspect
Show detailed information about a VM.
.TP
.BR vm\ start
Start one or more stopped VMs.
.TP
.BR vm\ stop
Stop one or more running VMs.
.TP
.BR vm\ pause
Pause one or more running VMs.
.TP
.BR vm\ resume
Resume one or more paused VMs.
.TP
.BR vm\ reboot
Reboot one or more VMs.
.SS Host Configuration
.TP
.BR host\ init
Apply host configuration (KVM, modules, ip_forward, mvm group, sudoers).
.TP
.BR host\ status
Show current host configuration state vs expected.
.TP
.BR host\ info
Show host hardware, limits, and VM capacity projection.
.TP
.BR host\ clean
Remove networking config (bridges, TAPs, firewall rules).
.TP
.BR host\ reset
Full rollback: networking + sysctl + sudoers + group removal.
.SS Kernel Management
.TP
.BR kernel\ ls
List cached kernels.
.TP
.BR kernel\ pull
Pull or build a kernel (official or Firecracker-optimized).
.TP
.BR kernel\ import
Register a pre-built vmlinux file as a kernel.
.TP
.BR kernel\ default
Set a kernel as the default for VM creation.
.TP
.BR kernel\ inspect
Show detailed information about a kernel.
.TP
.BR kernel\ rm
Remove a cached kernel.
.SS Image Management
.TP
.BR image\ ls
List available and cached images.
.TP
.BR image\ pull
Pull an image by its ID (e.g., ubuntu:24.04, archlinux).
.TP
.BR image\ import
Import a local image file.
.TP
.BR image\ default
Set the default image for VM creation.
.TP
.BR image\ rm
Remove a cached image.
.TP
.BR image\ inspect
Show detailed image information.
.TP
.BR image\ warm
Pre-decompress image to ready pool.
.SS Binary Management
.TP
.BR bin\ ls
List local Firecracker versions.
.TP
.BR bin\ pull
Download a Firecracker version or build from source.
.TP
.BR bin\ default
Set the active Firecracker version.
.TP
.BR bin\ rm
Remove a cached version.
.SS Volume Management
.TP
.BR volume\ create
Create a new persistent volume.
.TP
.BR volume\ rm
Remove one or more volumes.
.TP
.BR volume\ ls
List all volumes.
.TP
.BR volume\ inspect
Show detailed information about a volume.
.TP
.BR volume\ resize
Resize an existing volume.
.TP
.BR volume\ attach
Attach a volume to a running VM.
.TP
.BR volume\ detach
Detach a volume from a VM.
.SS Network Management
.TP
.BR network\ create
Create a named bridge network.
.TP
.BR network\ rm
Remove a named network.
.TP
.BR network\ ls
List all networks.
.TP
.BR network\ inspect
Show network details and IP leases.
.TP
.BR network\ default
Set a network as the default for VM creation.
.TP
.BR network\ sync
Sync firewall rules between database and host.
.SS SSH Key Management
.TP
.BR key\ ls
List cached keys.
.TP
.BR key\ import
Import an existing public key.
.TP
.BR key\ create
Generate a new SSH keypair (ed25519, rsa, or ecdsa).
.TP
.BR key\ rm
Remove a key from the cache.
.TP
.BR key\ default
Set one or more keys as defaults for new VMs.
.TP
.BR key\ inspect
Show detailed information about a key.
.TP
.BR key\ export
Export a key to ~/.ssh or a custom directory.
.SS Snapshot Management
.TP
.BR snapshot\ create
Snapshot a running VM.
.TP
.BR snapshot\ ls
List all snapshots.
.TP
.BR snapshot\ inspect
Show detailed information about a snapshot.
.TP
.BR snapshot\ restore
Restore a VM from a snapshot.
.TP
.BR snapshot\ rm
Remove one or more snapshots.
.SS Cache Management
.TP
.BR cache\ init
Initialize cache directories.
.TP
.BR cache\ prune
Prune stale cache entries (VMs, networks, images, kernels).
.TP
.BR cache\ clean
Completely clean all cache — prune everything, host clean, remove cache dir.
.SS Other Commands
.TP
.BR console
VM console access (PTY relay).
.RS
.PP
.B \-\-state
Show console connection state and exit.
.PP
.B \-\-kill
Kill any existing console connection to the VM.
.RE
.TP
.BR config
Configuration management (get, set, ls, reset).
.TP
.BR env
Environment workflow management (apply, ls, diff, destroy).
.TP
.BR init
Initialize mvm (guided setup wizard).
.TP
.BR ssh
VM SSH access.
.RS
.PP
.B \-\-user
SSH remote user (default: root).
.PP
.B \-\-key
Path to SSH key to use.
.PP
.B \-\-cmd
Run a command and exit instead of opening a session.
.PP
.B \-\-timeout
Connect/probe timeout (default: 5s, max: 10s).
.RE
.TP
.BR exec
Execute commands inside a VM via vsock agent (faster than SSH).
.RS
.PP
.B \-\-port
Vsock port (default: 1024).
.PP
.B \-\-timeout
Connect/probe timeout (default: 5s).
.PP
.B \-\-user
Remote user (default: root).
.RE
.TP
.BR logs
VM log management.
.RS
.PP
.B \-\-os
Show Firecracker OS log instead of boot log.
.PP
.B \-\-follow
Follow log output in real-time (tail -f style).
.PP
.B \-\-lines
Number of lines to show (default: 50).
.RE
.TP
.BR cp
Copy files between host and VM.
.RS
.PP
.B \-\-force
Overwrite existing files.
.PP
.B \-\-no-sync
Skip cache sync before copying.
.RE
.TP
.BR version
Show the mvm version and build information.
.TP
.BR self-update
Check for and apply binary updates from GitHub Releases.
.RE
.TP
.BR completion
Generate shell completion script (bash, zsh, or fish).
.TP
.BR help
Show help for mvm or a subcommand.
.SH SERVICE COMMANDS
All services are compiled into the single \fBmvm\fR binary.
No separate service binaries, no extraction step.
.TP
.BR mvm\ run\ console\ relay
Bidirectional PTY-to-socket relay for VM serial console access.
Bridges Firecracker's serial console (Unix socket) to a host PTY,
enabling interactive console access without SSH.
.TP
.BR mvm\ run\ nocloudnet\ serve
HTTP server for the nocloud-net cloud-init datasource.
Serves meta-data, user-data, and network-config to VMs during
cloud-init provisioning.
.TP
.BR mvm\ run\ provision
Privileged helper for loop-mount provisioning of root filesystem
images. Handles partition detection, mounting, file operations,
chroot commands, and filesystem resize (ext4/btrfs grow and shrink).
Requires passwordless sudo access.
.SH ENVIRONMENT
.TP
.BR MVM_CACHE_DIR
Override cache directory (default: ~/.cache/mvmctl).
.TP
.BR MVM_CONFIG_DIR
Override config directory (default: ~/.config/mvmctl).
.TP
.BR MVM_LOG_LEVEL
Set log level (DEBUG, INFO, WARNING, ERROR, default: WARNING).
.TP
.BR MVM_ASSET_MIRROR
Local mirror directory for downloaded assets (default: not set).
.TP
.BR MVM_WARM_POOL
Set to "disk" to use disk-based warm pool (default: tmpfs).
.TP
.BR MVM_TEMP_DIR
Override temp directory (default: /tmp/mvmctl).
.TP
.BR MVM_ESCALATED
Set by sudo wrapper to indicate privilege escalation (default: not set).
.TP
.BR MVM_SUDO_RESTART
Set internally when re-running with sudo for host init (default: not set).
.SH FILES
.TP
.I ~/.cache/mvmctl/
Cache directory for binaries, kernels, images, volumes, VM state.
.TP
.I ~/.cache/mvmctl/mvmdb.db
SQLite database (canonical store for images, kernels, binaries, VMs, networks, keys, settings).
.SH EXAMPLES
.PP
One-time host setup:
.RS
.nf
$ mvm init
# Log out and back in, or run: newgrp mvm
.fi
.RE
.PP
Download kernel and image:
.RS
.nf
$ mvm kernel pull
$ mvm image pull ubuntu:24.04
.fi
.RE
.PP
Create and start a VM:
.RS
.nf
$ mvm vm create myvm --image ubuntu:24.04
$ mvm logs myvm --follow
$ mvm ssh myvm
.fi
.RE
.PP
List and remove VMs:
.RS
.nf
$ mvm vm ls
$ mvm vm rm myvm --force
.fi
.RE
.PP
Network management:
.RS
.nf
$ mvm network create mynet --subnet 10.1.0.0/16
$ mvm vm create myvm2 --image ubuntu:24.04 --network mynet
.fi
.RE
.PP
Run interactive setup wizard:
.RS
.nf
$ mvm init
.fi
.RE
.SH PREREQUISITES
.IP \(bu 2
Linux (x86_64 or aarch64) - Firecracker only runs on Linux
.IP \(bu 2
KVM access (/dev/kvm) - add user to kvm group
.IP \(bu 2
System packages: iproute2, iptables/nftables, qemu-utils, e2fsprogs, util-linux, openssh-client, tar, procps, kmod, sudo, passwd, fakeroot
.SH NOTES
.IP \(bu 2
After \fBmvm init\fR, normal mvm commands require no sudo.
.IP \(bu 2
Cache is stored at ~/.cache/mvmctl/ by default.
.IP \(bu 2
All assets are keyed by SHA256 hash (64 characters).
.IP \(bu 2
CLI displays only first 6 characters of hashes as short IDs.
.SH SEE ALSO
.BR firecracker (1),
.BR iptables (8),
.BR nft (8),
.BR ip (8)
.SH BUGS
Report bugs at: https://github.com/AlanD20/mvmctl/issues
.SH AUTHOR
AlanD20 and contributors
.SH LICENSE
MIT License