Lume CLI Reference

Once installed, you can start using Lume with these common workflows:

Run a Prebuilt VM

# Run a macOS Sequoia VM
lume run macos-sequoia-vanilla:latest

# Run an Ubuntu VM
lume run ubuntu-noble-vanilla:latest

We provide prebuilt VM images in our ghcr registry.

Create a Custom VM

# Create a new macOS VM
lume create my-macos-vm --cpu 4 --memory 8GB --disk-size 50GB

# Create a Linux VM
lume create my-linux-vm --os linux --cpu 2 --memory 4GB

Disk Space

The actual disk space used by sparse images will be much lower than the logical size listed. You can resize VM disks after creation using lume set <name> --disk-size <size>.

VM Management

lume create <name> Create a new macOS or Linux virtual machine.

Options:

--os <os> - Operating system to install (macOS or linux, default: macOS)
--cpu <cores> - Number of CPU cores (default: 4)
--memory <size> - Memory size, e.g., 8GB (default: 4GB)
--disk-size <size> - Disk size, e.g., 50GB (default: 40GB)
--display <res> - Display resolution (default: 1024x768)
--ipsw <path> - Path to IPSW file or 'latest' for macOS VMs
--storage <name> - VM storage location to use

Examples:

# Create macOS VM with custom specs
lume create my-mac --cpu 6 --memory 16GB --disk-size 100GB

# Create Linux VM
lume create my-ubuntu --os linux --cpu 2 --memory 8GB

# Create macOS VM with latest IPSW
lume create my-sequoia --ipsw latest

lume run <name> Start and run a virtual machine.

Options:

--no-display - Do not start the VNC client app
--shared-dir <dir> - Share directory with VM (format: path[:ro|rw])
--mount <path> - For Linux VMs only, attach a read-only disk image
--registry <url> - Container registry URL (default: ghcr.io)
--organization <org> - Organization to pull from (default: trycua)
--vnc-port <port> - Port to use for the VNC server (default: 0 for auto-assign)
--recovery-mode <boolean> - For macOS VMs only, start VM in recovery mode (default: false)
--storage <name> - VM storage location to use

Examples:

# Run VM with shared directory
lume run my-vm --shared-dir /path/to/share:rw

# Run VM without display (headless)
lume run my-vm --no-display

# Run macOS VM in recovery mode
lume run my-mac --recovery-mode true

lume stop <name> Stop a running virtual machine.

Options:

--storage <name> - VM storage location to use

lume delete <name>

Delete a virtual machine and its associated files.

Options:

--force - Force deletion without confirmation
--storage <name> - VM storage location to use

lume clone <name> <new-name>

Create a copy of an existing virtual machine.

Options:

--source-storage <name> - Source VM storage location
--dest-storage <name> - Destination VM storage location

VM Information and Configuration

lume ls

List all virtual machines and their status.

lume get <name>

Get detailed information about a specific virtual machine.

Options:

-f, --format <format> - Output format (json|text)
--storage <name> - VM storage location to use

lume set <name>

Modify virtual machine configuration.

Options:

--cpu <cores> - New number of CPU cores (e.g., 4)
--memory <size> - New memory size (e.g., 8192MB or 8GB)
--disk-size <size> - New disk size (e.g., 40960MB or 40GB)
--display <res> - New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)
--storage <name> - VM storage location to use

Examples:

# Increase VM memory
lume set my-vm --memory 16GB

# Change display resolution
lume set my-vm --display 1920x1080

# Add more CPU cores
lume set my-vm --cpu 8

Image Management

lume images

List available macOS images in local cache.

lume pull <image>

Download a VM image from a container registry.

Options:

--registry <url> - Container registry URL (default: ghcr.io)
--organization <org> - Organization to pull from (default: trycua)
--storage <name> - VM storage location to use

lume push <name> <image:tag>

Upload a VM image to a container registry.

Options:

--additional-tags <tags...> - Additional tags to push the same image to
--registry <url> - Container registry URL (default: ghcr.io)
--organization <org> - Organization/user to push to (default: trycua)
--storage <name> - VM storage location to use
--chunk-size-mb <size> - Chunk size for disk image upload in MB (default: 512)
--verbose - Enable verbose logging
--dry-run - Prepare files and show plan without uploading
--reassemble - Verify integrity by reassembling chunks (requires --dry-run)