Lume CLI Reference

A lightweight CLI and local API server to build, run and manage macOS VMs.

Quick Start

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

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

VM Management

lume create

Create a new virtual machine

Arguments:

• <name> - Name for the virtual machine

Options:

• --os - Operating system to install (macOS or linux) (default: macOS)
• --cpu - Number of CPU cores (default: 4)
• --memory - Memory size (e.g., 8GB) (default: 8GB)
• --disk-size - Disk size (e.g., 50GB) (default: 50GB)
• --display - Display resolution (e.g., 1024x768) (default: 1024x768)
• --ipsw - Path to IPSW file or 'latest' for macOS VMs
• --storage - VM storage location to use
• --unattended - [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe. Only supported for macOS VMs.
• --debug-dir - Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp)
• --vnc-port - Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign) (default: 0)

Flags:

• --debug - Enable debug mode for unattended setup - saves screenshots with click coordinates
• --no-display - Do not open the VNC client during unattended setup (default: true for unattended)

lume clone

Clone an existing virtual machine

Arguments:

• <name> - Name of the source VM
• <new-name> - Name for the cloned VM

Options:

• --source-storage - Source VM storage location
• --dest-storage - Destination VM storage location

lume run

Run a virtual machine

Arguments:

• <name> - Name of the VM or image to run (format: name or name:tag)

Options:

• --shared-dir - Directory to share with the VM (format: path or path:ro or path:rw)
• --mount - For Linux VMs only, attach a read-only disk image
• --usb-storage - Disk image to attach as USB mass storage device
• --registry - Container registry URL (default: ghcr.io)
• --organization - Organization to pull from (default: trycua)
• --vnc-port - Port for VNC server (0 for auto-assign) (default: 0)
• --recovery-mode - For macOS VMs only, boot in recovery mode (default: false)
• --storage - VM storage location to use

Flags:

• -d, --no-display - Do not start the VNC client

lume stop

Stop a virtual machine

Arguments:

• <name> - Name of the VM to stop

Options:

• --storage - VM storage location to use

lume delete

Delete a virtual machine

Arguments:

• <name> - Name of the VM to delete

Options:

• --storage - VM storage location to use

Flags:

• --force - Force deletion without confirmation

VM Information and Configuration

lume get

Get detailed information about a virtual machine

Arguments:

• <name> - Name of the VM

Options:

• -f, --format - Output format (default: text)
• --storage - VM storage location to use

lume set

Set new values for CPU, memory, and disk size of a virtual machine

Arguments:

• <name> - Name of the VM

Options:

• --cpu - New number of CPU cores
• --memory - New memory size (e.g., 8GB)
• --disk-size - New disk size (e.g., 100GB)
• --display - New display resolution
• --storage - VM storage location to use

lume ls

List virtual machines

Options:

• -f, --format - Output format (json or text) (default: text)
• --storage - Filter by storage location name

Image Management

lume pull

Pull a macOS image from GitHub Container Registry

Arguments:

• <image> - Image to pull (format: name:tag)
• <name> - Name for the resulting VM (optional)

Options:

• --registry - Container registry URL (default: ghcr.io)
• --organization - Organization to pull from (default: trycua)
• --storage - VM storage location to use

lume push

Push a macOS VM to GitHub Container Registry

Arguments:

• <name> - Name of VM to push
• <image> - Image tag (format: name:tag)

Options:

• --additional-tags - Additional tags to push
• --registry - Container registry URL (default: ghcr.io)
• --organization - Organization to push to (default: trycua)
• --storage - VM storage location to use
• --chunk-size-mb - Chunk size for upload in MB (default: 512)

Flags:

• --verbose - Enable verbose logging
• --dry-run - Prepare files without uploading
• --reassemble - Verify integrity by reassembling chunks

lume images

List available macOS images from local cache

Options:

• --organization - Organization to list images for (default: trycua)

lume ipsw

Get macOS restore image IPSW URL

lume prune

Remove cached images

Configuration and Server

lume serve

Start the VM management server

Options:

• --port - Port to listen on (default: 7777)

lume config

Get or set lume configuration

Subcommands:

• lume config get - Get current configuration
• lume config storage - Manage VM storage locations
  • lume config storage add - Add a new VM storage location
  • lume config storage remove - Remove a VM storage location
  • lume config storage list - List all VM storage locations
  • lume config storage default - Set the default VM storage location
• lume config cache - Manage cache settings
  • lume config cache get - Get current cache directory
  • lume config cache set - Set cache directory
• lume config caching - Manage image caching settings
  • lume config caching get - Show current caching status
  • lume config caching set - Enable or disable image caching

lume logs

View lume serve logs

Subcommands:

• lume logs info - View info logs from the daemon
  • -n, --lines - Number of lines to display
• lume logs error - View error logs from the daemon
  • -n, --lines - Number of lines to display
• lume logs all - View both info and error logs
  • -n, --lines - Number of lines to display

lume setup

[Preview] Run unattended Setup Assistant automation on a macOS VM

Arguments:

• <name> - Name of the virtual machine

Options:

• --unattended - Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: tahoe.
• --storage - VM storage location to use or direct path to VM location
• --vnc-port - Port to use for the VNC server. Defaults to 0 (auto-assign) (default: 0)
• --debug-dir - Custom directory for debug screenshots (defaults to unique folder in system temp)

Flags:

• --no-display - Do not open the VNC client automatically
• --debug - Enable debug mode - saves screenshots with click coordinates

Global Options

These options are available for all commands:

• --help - Show help information
• --version - Show version number