CLI Reference

Command Line Interface reference for Lume

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

Documented against Lume 0.3.10. Run lume --version for your installed version.

For installation steps, see Install Lume.

VM Management#

lume create#

Create a new virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name for the virtual machine

Options:

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

Flags:

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

lume clone#

Clone an existing virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the source VM
`<new-name>`	String	Yes	Name for the cloned VM

Options:

Name	Type	Default	Description
`--source-storage`	String	-	Source VM storage location
`--dest-storage`	String	-	Destination VM storage location

lume run#

Run a virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the VM or image to run (format: name or name:tag)

Options:

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

Flags:

Name	Default	Description
`-d, --no-display`	false	Do not start the VNC client

lume stop#

Stop a virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the VM to stop

Options:

Name	Type	Default	Description
`--storage`	String	-	VM storage location to use

lume delete#

Delete a virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the VM to delete

Options:

Name	Type	Default	Description
`--storage`	String	-	VM storage location to use

Flags:

Name	Default	Description
`--force`	false	Force deletion without confirmation

VM Information and Configuration#

lume get#

Get detailed information about a virtual machine

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the VM

Options:

Name	Type	Default	Description
`-f, --format`	String	text	Output format
`--storage`	String	-	VM storage location to use

lume set#

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

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the VM

Options:

Name	Type	Default	Description
`--cpu`	Int	-	New number of CPU cores
`--memory`	String	-	New memory size (e.g., 8GB)
`--disk-size`	String	-	New disk size (e.g., 100GB)
`--display`	String	-	New display resolution
`--storage`	String	-	VM storage location to use

lume ls#

List virtual machines

Options:

Name	Type	Default	Description
`-f, --format`	String	text	Output format (json or text)
`--storage`	String	-	Filter by storage location name

Image Management#

lume pull#

Pull a macOS image from GitHub Container Registry

Arguments:

Name	Type	Required	Description
`<image>`	String	Yes	Image to pull (format: name:tag)
`<name>`	String	No	Name for the resulting VM

Options:

Name	Type	Default	Description
`--registry`	String	ghcr.io	Container registry URL
`--organization`	String	trycua	Organization to pull from
`--storage`	String	-	VM storage location to use

lume push#

Push a macOS VM to GitHub Container Registry

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of VM to push
`<image>`	String	Yes	Image tag (format: name:tag)

Options:

Name	Type	Default	Description
`--additional-tags`	[String]	-	Additional tags to push
`--registry`	String	ghcr.io	Container registry URL
`--organization`	String	trycua	Organization to push to
`--storage`	String	-	VM storage location to use
`--chunk-size-mb`	Int	512	Chunk size for upload in MB

Flags:

Name	Default	Description
`--verbose`	false	Enable verbose logging
`--dry-run`	false	Prepare files without uploading
`--reassemble`	true	Verify integrity by reassembling chunks

lume images#

List available macOS images from local cache

Options:

Name	Type	Default	Description
`--organization`	String	trycua	Organization to list images for

lume ipsw#

Get macOS restore image IPSW URL

lume prune#

Remove cached images

Guest Access and Setup#

lume ssh#

Connect to a VM via SSH or execute commands remotely

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the virtual machine
`<command>`	[String]	No	Command to execute (omit for interactive shell)

Options:

Name	Type	Default	Description
`-u, --user`	String	lume	SSH username
`-p, --password`	String	lume	SSH password
`--storage`	String	-	Storage location name or path
`-t, --timeout`	Int	60	Command timeout in seconds (0 for no timeout)

lume setup#

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

Arguments:

Name	Type	Required	Description
`<name>`	String	Yes	Name of the virtual machine

Options:

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

Flags:

Name	Default	Description
`--no-display`	false	Do not open the VNC client automatically
`--debug`	false	Enable debug mode - saves screenshots with click coordinates

Configuration and Server#

lume serve#

Start the VM management server

Options:

Name	Type	Default	Description
`--port`	Int	7777	Port to listen on

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 image cache settings
- lume config cache status - Show cache status and directory
- lume config cache dir - Get or set cache directory
- lume config cache enable - Enable image caching
- lume config cache disable - 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

Global Options#

These options are available for all commands:

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