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.16. 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	100GB for macOS; 50GB for Linux	Disk size (e.g., 100GB)
`--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	-	Prepare macOS unattended setup offline after install. Preset name or YAML path is accepted for compatibility. Built-in presets: sequoia, tahoe. Only supported for macOS VMs.
`--debug-dir`	String	-	Compatibility option; ignored by offline setup.
`--vnc-port`	Int	0	Port to use for the temporary verification VNC server. Defaults to 0 (auto-assign).

Flags:

Name	Default	Description
`--debug`	false	Compatibility flag; ignored by offline setup.
`--no-display`	false	Compatibility flag; offline setup verifies headlessly.

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

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

VM Information and Configuration#

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

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 total disk size. Increase only; macOS resizing preserves RecoveryOS and grows APFS.
`--display`	String	-	New display resolution
`--storage`	String	-	VM storage location to use

Flags:

Name	Default	Description
`--no-backup`	false	Skip the macOS rollback backup
`--keep-backup`	false	Keep rollback files after a successful macOS resize
`--dry-run`	false	Validate the resize plan without modifying the disk

Image Management#

lume images#

List available macOS images from local cache

Options:

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

lume pull#

Pull a prebuilt or custom macOS image from an OCI-compatible 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 an OCI-compatible 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 convert#

Convert a legacy Lume image to OCI-compliant format

Arguments:

Name	Type	Required	Description
`<source-image>`	String	Yes	Source image to convert (legacy format, for example macos-tahoe:latest)
`<target-image>`	String	Yes	Target image to push in OCI format (name:tag)

Options:

Name	Type	Default	Description
`--additional-tags`	[String]	-	Additional tags for the OCI image
`--registry`	String	ghcr.io	Registry to pull from and push to
`--organization`	String	trycua	Registry organization

Flags:

Name	Default	Description
`--verbose`	false	Enable verbose logging
`--dry-run`	false	Prepare files without uploading
`--single-layer`	false	Push one kubelet-compatible disk layer

lume ipsw#

Get macOS restore image IPSW URL

lume prune#

Remove cached images

Guest Access and Security#

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#

Prepare unattended macOS setup

Arguments:

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

Options:

Name	Type	Default	Description
`--unattended`	String	tahoe	Defaults to tahoe. Preset name or YAML path for compatibility and optional post-SSH commands. 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 temporary verification VNC server. Defaults to 0 (auto-assign)
`--debug-dir`	String	-	Compatibility option; ignored by offline setup

Flags:

Name	Default	Description
`--no-display`	false	Compatibility flag; offline setup verifies headlessly
`--debug`	false	Compatibility flag; ignored by offline setup

lume sip#

Enable or disable System Integrity Protection on a macOS VM

Arguments:

Name	Type	Required	Description
`<state>`	String	Yes	Desired SIP state: on or off
`<name>`	String	Yes	Name of the virtual machine

Options:

Name	Type	Default	Description
`--admin-user`	String	lume	Administrator username in the guest
`--admin-password`	String	-	Administrator password in the guest; prefer --admin-password-stdin
`--screenshot-dir`	String	-	Directory for Recovery framebuffer screenshots
`--vnc-port`	Int	5999	Port for the temporary Recovery VNC server
`--storage`	String	-	VM storage location
`--timeout`	Int	900	Overall timeout in seconds

Flags:

Name	Default	Description
`-y, --yes`	false	Skip the interactive confirmation prompt
`--admin-password-stdin`	false	Read one administrator-password line from standard input without echo

Configuration and Server#

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 config telemetry - Manage pseudonymous telemetry settings
- lume config telemetry status - Show current telemetry status
- lume config telemetry enable - Enable pseudonymous telemetry
- lume config telemetry disable - Disable pseudonymous telemetry
- lume config telemetry reset-id - Delete the pseudonymous installation ID and registration markers

lume serve#

Start the VM management server

Options:

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

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 check-update#

Check whether a newer Lume release is available

Flags:

Name	Default	Description
`--json`	false	Emit the structured update-state payload as JSON
`--no-cache`	false	Bypass the local update-check cache

lume update#

Check for a Lume update and optionally apply it

Flags:

Name	Default	Description
`--apply`	false	Apply the update by re-running the official installer
`--json`	false	Emit the structured update-state payload as JSON

Developer Tools#

lume dump-docs#

Output CLI and API documentation as JSON for tooling and integrations

Options:

Name	Type	Default	Description
`--type`	String	cli	Documentation type: cli, api, or all

Flags:

Name	Default	Description
`--pretty`	false	Pretty-print JSON output

Global Options#

These options are available for all commands:

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