lume CLI

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

lume [OPTIONS] <COMMAND>

Run lume <command> --help for the build you have.

Commands#

Command	Description
`lume create`	Create a new virtual machine.
`lume run`	Run a virtual machine.
`lume attach`	Open a viewer for a running virtual machine.
`lume stop`	Stop a virtual machine.
`lume shutdown`	Gracefully shut down a virtual machine.
`lume restart`	Gracefully restart a virtual machine.
`lume ls`	List virtual machines.
`lume get`	Get detailed information about a virtual machine.
`lume set`	Set new values for CPU, memory, and disk size of a virtual machine.
`lume clone`	Clone an existing virtual machine.
`lume delete`	Delete a virtual machine.
`lume images`	List available macOS images from local cache.
`lume pull`	Pull a prebuilt or custom macOS image from an OCI-compatible registry.
`lume push`	Push a macOS VM to an OCI-compatible registry.
`lume convert`	Convert a legacy Lume image to OCI-compliant format.
`lume ipsw`	Get macOS restore image IPSW URL.
`lume prune`	Remove cached images.
`lume setup`	Prepare unattended macOS setup.
`lume ssh`	Connect to a VM via SSH or execute commands remotely.
`lume cp`	Copy files between the host and a VM.
`lume sip`	Enable or disable System Integrity Protection on a macOS VM.
`lume serve`	Start the VM management server.
`lume logs`	View lume serve logs.
`lume logs info`	View info logs from the daemon.
`lume logs error`	View error logs from the daemon.
`lume logs all`	View both info and error logs from the daemon.
`lume dump-docs`	Output CLI and API documentation as JSON for tooling and integrations.
`lume config`	Get or set lume configuration.
`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 dir`	Get or set cache directory.
`lume config cache enable`	Enable image caching.
`lume config cache disable`	Disable image caching.
`lume config cache status`	Show cache status and directory.
`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 config registry`	Manage container registry settings.
`lume config registry status`	Show current registry configuration.
`lume config registry type`	Get or set registry type.
`lume config registry ghcr`	Configure GitHub Container Registry settings.
`lume config registry gcs`	Configure GCS registry settings.
`lume config network`	Manage network settings.
`lume config network interfaces`	List available network interfaces for bridged networking.
`lume check-update`	Check whether a newer Lume release is available.
`lume update`	Check for a Lume update and optionally apply it.
`lume channel`	Inspect or change the stable/nightly update channel; selection does not install.
`lume channel status`	Show selected and current release channels.
`lume channel set`	Save stable or nightly as the update channel.

VMs#

Create, run, inspect, change, clone and delete virtual machines.

`lume create`#

Create a new virtual machine.

lume create [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name for the virtual machine.

Flag	Type	Default	Description
`--os`	string	`macOS`	Operating system to install: macOS or linux.
`--cpu`	integer	`4`	Number of CPU cores.
`--memory`	string	`8GB`	Memory size (8, 8GB or 8192MB; a bare number is GB).
`--disk-size`	string		Disk size (100, 100GB or 102400MB; a bare number is GB). Defaults to 100GB for macOS and 50GB for Linux.
`--display`	string	`1024x768`	Display resolution as WIDTHxHEIGHT.
`--ipsw`	string		Path to a macOS restore image (IPSW), or 'latest' to download the latest supported version. Required for macOS VMs.
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--unattended`	string		Prepare macOS unattended setup offline after install. Built-in presets: sequoia, tahoe; a YAML path is accepted for compatibility. macOS VMs only.
`--debug-dir`	string		Compatibility option; ignored by offline setup.
`--vnc-port`	integer	`0`	Port for the temporary verification VNC server (0 picks a free port).
`--network`	string	`nat`	Network mode: nat, bridged (picks an interface), or bridged:<interface> (for example bridged:en0).
`--debug`	boolean	`false`	Compatibility flag; ignored by offline setup.
`--no-display`	boolean	`false`	Compatibility flag; offline setup verifies headlessly.

Examples

# A macOS VM from the latest IPSW, set up unattended (SSH user lume/lume)
lume create macos-tahoe --ipsw latest --unattended tahoe
 
# A Linux VM
lume create dev --os linux --cpu 4 --memory 8GB --disk-size 50GB
 
# Bridge the VM onto the host's en0 network
lume create macos-tahoe --ipsw latest --network bridged:en0

`lume run`#

Run a virtual machine.

lume run [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM, or an image to pull and run (format: name or name:tag).

Flag	Short	Type	Default	Description
`--display`		`vnc` \| `native` \| `none`	`native`	Local viewer to open. The VNC server stays available in every mode.
`--log-file`		string		Log path for --detach (default: ~/Library/Logs/lume/{vm}.log).
`--shared-dir`		string		Directory to share with the VM: a path (read-write) or path:ro / path:rw. Repeatable.
`--mount`		string		For Linux VMs only, a read-only disk image to attach.
`--usb-storage`		string		Disk image to attach as a USB mass storage device. Repeatable.
`--disk`		string		Disk image to attach as a read-write virtio-blk device. Repeatable.
`--registry`		string	`ghcr.io`	Container registry to pull images from.
`--organization`		string	`trycua`	Organization to pull images from.
`--vnc`		`enabled` \| `disabled`	`enabled`	VNC server policy. disabled starts the VM with no VNC listener and reports a null vncUrl.
`--vnc-port`		integer	`0`	Port for the VNC server (0 picks a free port).
`--vnc-password`		string		Password for the VNC server (default: a random passphrase).
`--recovery-mode`		boolean	`false`	For macOS VMs only, boot into recovery mode.
`--storage`		string		VM storage location name, or a direct path to the VM location.
`--disk-path`		string		Use this disk image instead of disk.img in the VM directory.
`--nvram-path`		string		Use this NVRAM file instead of nvram.bin in the VM directory.
`--network`		string		Network override for this run: nat, bridged, or bridged:<interface> (default: the VM's configured mode).
`--no-display`	`-d`	boolean	`false`	Compatibility alias for --display none.
`--detach`		boolean	`false`	Run the VM in the background and return immediately.
`--clipboard`		boolean	`false`	Sync the clipboard both ways over SSH. Automatic with the native macOS display.

Examples

lume run my-vm
 
# Headless, with a read-only shared folder
lume run my-vm --shared-dir ~/src:ro --display none
 
# In the background with no VNC listener
lume run my-vm --detach --display none --vnc disabled

`lume attach`#

Open a viewer for a running virtual machine.

The native display is used when the lume run process that owns the VM supports live attachment; VNC is the fallback.

lume attach [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the virtual machine.

Flag	Type	Default	Description
`--display`	`native` \| `vnc`		Viewer to open (default: native, falling back to VNC).
`--storage`	string		VM storage location to use.

Examples

lume attach my-vm
 
# Open Screen Sharing over VNC
lume attach my-vm --display vnc

`lume stop`#

Stop a virtual machine.

lume stop [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM to stop.

Flag	Type	Default	Description
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--timeout`	integer	`10`	Seconds to wait for a graceful shutdown before forcing power off.
`--force`	boolean	`false`	Power off the VM immediately instead of attempting a graceful shutdown first.

Examples

lume stop my-vm
lume stop my-vm --force

`lume shutdown`#

Gracefully shut down a virtual machine.

Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.

lume shutdown [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the virtual machine.

Flag	Short	Type	Default	Description
`--user`	`-u`	string	`lume`	SSH username.
`--password`	`-p`	string	`lume`	SSH and sudo password.
`--storage`		string		VM storage location to use.
`--timeout`	`-t`	integer	`30`	SSH command timeout in seconds.

Examples

lume shutdown my-vm
 
# With another SSH user and a longer timeout
lume shutdown my-vm --user admin --timeout 60

`lume restart`#

Gracefully restart a virtual machine.

Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.

lume restart [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the virtual machine.

Flag	Short	Type	Default	Description
`--user`	`-u`	string	`lume`	SSH username.
`--password`	`-p`	string	`lume`	SSH and sudo password.
`--storage`		string		VM storage location to use.
`--timeout`	`-t`	integer	`30`	SSH command timeout in seconds.

Examples

lume restart my-vm
 
# With another SSH user and a longer timeout
lume restart my-vm --user admin --timeout 60

`lume ls`#

List virtual machines.

lume ls [OPTIONS]

Flag	Short	Type	Default	Description
`--format`	`-f`	`json` \| `text`	`text`	Output format.
`--storage`		string		Show only VMs in this storage location.

Examples

lume ls
lume ls --format json

`lume get`#

Get detailed information about a virtual machine.

lume get [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM.

Flag	Short	Type	Default	Description
`--format`	`-f`	`json` \| `text`	`text`	Output format.
`--storage`		string		VM storage location name, or a direct path to the VM location.

Examples

lume get my-vm
 
# Machine-readable, including the IP address and VNC URL
lume get my-vm --format json

`lume set`#

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

lume set [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM.

Flag	Type	Default	Description
`--cpu`	integer		New number of CPU cores.
`--memory`	string		New memory size (8, 8GB or 8192MB; a bare number is GB).
`--disk-size`	string		New total disk size, increase only. For macOS VMs this relocates the recovery partition and grows the main APFS container; the VM must be stopped and it may take several minutes.
`--display`	string		New display resolution as WIDTHxHEIGHT.
`--machine-identifier`	string		New machine identifier: 'random', or a base64 identifier from `lume get --format json` to give this VM an existing machine identity (per-machine licenses then see one machine). macOS VMs only; the VM must be stopped.
`--mac-address`	string		New MAC address: 'random' (locally administered) or aa:bb:cc:dd:ee:ff. The VM must be stopped. The DHCP lease follows the MAC, so two running VMs with one MAC claim the same IP.
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--no-backup`	boolean	`false`	Skip the pre-resize disk backup (macOS resize only). Faster, but a failure cannot be rolled back.
`--keep-backup`	boolean	`false`	Keep the pre-resize backup after a successful macOS resize.
`--dry-run`	boolean	`false`	Validate the disk-resize plan and print it without changing anything (macOS resize only).

Examples

lume set my-vm --cpu 8 --memory 16GB
 
# Check a disk resize plan, then run it without --dry-run
lume set my-vm --disk-size 120GB --dry-run
lume set my-vm --mac-address random

`lume clone`#

Clone an existing virtual machine.

lume clone [OPTIONS] <name> <new-name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the source VM.
`<new-name>`	string	required	Name for the cloned VM.

Flag	Type	Default	Description
`--source-storage`	string		Source VM storage location.
`--dest-storage`	string		Destination VM storage location.

Examples

# Keep a golden copy before changing a VM
lume clone macos-tahoe macos-tahoe-backup
 
# Copy a VM to another storage location
lume clone macos-tahoe macos-tahoe --source-storage default --dest-storage external

`lume delete`#

Delete a virtual machine.

lume delete [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM to delete.

Flag	Type	Default	Description
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--force`	boolean	`false`	Delete without asking for confirmation.

Examples

lume delete my-vm
 
# Without the confirmation prompt
lume delete my-vm --force

Images#

Pull, push and convert VM images, find restore images, and prune the cache.

`lume images`#

List available macOS images from local cache.

lume images [OPTIONS]

Flag	Type	Default	Description
`--organization`	string	`trycua`	Organization to list images for.

Examples

lume images

`lume pull`#

Pull a prebuilt or custom macOS image from an OCI-compatible registry.

lume pull [OPTIONS] <image> [<name>]

Argument	Type	Default	Description
`<image>`	string	required	Image to pull (format: name:tag).
`<name>`	string	optional	Name for the resulting VM (defaults to the image name without its tag).

Flag	Type	Default	Description
`--registry`	string	`ghcr.io`	Container registry to pull from.
`--organization`	string	`trycua`	Organization to pull from.
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--username`	string		Registry username for authentication.
`--password`	string		Registry password for authentication.
`--force`	boolean	`false`	Download again even if the image is cached.
`--verbose`	boolean	`false`	Enable verbose logging.

Examples

# Pull an image from ghcr.io/trycua as a VM named macos-tahoe-vanilla
lume pull macos-tahoe-vanilla:latest
 
# Pull it as my-vm into another storage location
lume pull macos-tahoe-vanilla:latest my-vm --storage external

`lume push`#

Push a macOS VM to an OCI-compatible registry.

lume push [OPTIONS] <name> <image>

Argument	Type	Default	Description
`<name>`	string	required	Name of the VM to push.
`<image>`	string	required	Image tag to push (format: name:tag).

Flag	Type	Default	Description
`--additional-tags`	string		Additional tags to push the same image to. Takes one or more values.
`--registry`	string	`ghcr.io`	Container registry to push to.
`--organization`	string	`trycua`	Organization to push to.
`--storage`	string		VM storage location to use.
`--chunk-size-mb`	integer	`512`	Chunk size for large files, in MB.
`--verbose`	boolean	`false`	Enable verbose logging.
`--dry-run`	boolean	`false`	Prepare files without uploading to the registry.
`--reassemble`	boolean	`false`	With --dry-run, also reassemble the chunks to verify integrity.
`--single-layer`	boolean	`false`	Push the disk as a single layer (kubelet-compatible, no chunking).
`--legacy`	boolean	`false`	Use the legacy Lume LZ4-chunked format instead of the OCI-compliant format.

Examples

# Push my-vm as ghcr.io/my-org/my-image:latest
lume push my-vm my-image:latest --organization my-org
 
# Push one image under several tags
lume push my-vm my-image:1.0 --additional-tags latest stable
 
# Prepare and verify the chunks without uploading
lume push my-vm my-image:latest --dry-run --reassemble

`lume convert`#

Convert a legacy Lume image to OCI-compliant format.

Pulls a legacy Lume image from the registry, pushes it again in OCI-compliant format under a new name and tag, then removes the temporary local VM.

lume convert [OPTIONS] <source-image> <target-image>

Argument	Type	Default	Description
`<source-image>`	string	required	Source image to convert (legacy format, for example macos-tahoe:latest).
`<target-image>`	string	required	Target image to push in OCI format (format: name:tag).

Flag	Type	Default	Description
`--additional-tags`	string		Additional tags to push the OCI image to. Takes one or more values.
`--registry`	string	`ghcr.io`	Registry to pull from and push to.
`--organization`	string	`trycua`	Registry organization.
`--verbose`	boolean	`false`	Enable verbose logging.
`--dry-run`	boolean	`false`	Prepare files without uploading to the registry.
`--single-layer`	boolean	`false`	Push the disk as a single layer (kubelet-compatible, no chunking).

Examples

lume convert macos-tahoe:latest macos-tahoe:latest-oci

`lume ipsw`#

Get macOS restore image IPSW URL.

Prints the URL of the latest supported restore image. Download it, then pass the file to lume create --ipsw.

lume ipsw

Examples

lume ipsw

`lume prune`#

Remove cached images.

lume prune

Examples

lume prune

Guest access#

Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest.

`lume setup`#

Prepare unattended macOS setup.

Lume prepares the macOS disk offline, skips Setup Assistant, enables autologin and SSH, disables screensaver lock, verifies SSH, then stops the VM.

lume setup [OPTIONS] <name>

Argument	Type	Default	Description
`<name>`	string	required	Name of the virtual machine.

Flag	Type	Default	Description
`--unattended`	string		Built-in preset (sequoia, tahoe) or a YAML path, kept for compatibility and optional post-SSH commands (default: tahoe).
`--storage`	string		VM storage location name, or a direct path to the VM location.
`--vnc-port`	integer	`0`	Port for the temporary verification VNC server (0 picks a free port).
`--debug-dir`	string		Compatibility option; ignored by offline setup.
`--no-display`	boolean	`false`	Compatibility flag; offline setup verifies headlessly.
`--debug`	boolean	`false`	Compatibility flag; ignored by offline setup.

Examples

lume setup my-vm
lume setup my-vm --unattended sequoia

`lume ssh`#

Connect to a VM via SSH or execute commands remotely.

Opens an interactive shell, or runs one command and exits with its status. Password authentication is handled for you (no sshpass needed). Requires Remote Login in the guest; VMs created with --unattended have it enabled with credentials lume/lume.

lume ssh [OPTIONS] <name> [<command>...]

Argument	Type	Default	Description
`<name>`	string	required	Name of the virtual machine.
`<command>...`	string	optional	Command to execute (omit for an interactive shell). Repeatable.

Flag	Short	Type	Default	Description
`--user`	`-u`	string	`lume`	SSH username.
`--password`	`-p`	string	`lume`	SSH password.
`--storage`		string		Storage location name or path.
`--timeout`	`-t`	integer	`60`	Command timeout in seconds (0 for no timeout).

Examples

# Interactive shell
lume ssh my-vm
 
# Run one command
lume ssh my-vm "ls -la"
 
# A long-running command with no timeout
lume ssh my-vm --timeout 0 "cd /app && npm test"

`lume cp`#

Copy files between the host and a VM.

Copies a file or directory between the host and a running VM over SSH, using the same credentials as lume ssh. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.

lume cp [OPTIONS] <source> <destination>

Argument	Type	Default	Description
`<source>`	string	required	Source path. Use VM:PATH for a path inside a VM.
`<destination>`	string	required	Destination path. Use VM:PATH for a path inside a VM.

Flag	Short	Type	Default	Description
`--user`	`-u`	string	`lume`	SSH username.
`--password`	`-p`	string	`lume`	SSH password.
`--storage`		string		Storage location name or path.
`--timeout`	`-t`	integer	`600`	Transfer timeout in seconds (0 for no timeout).
`--recursive`	`-r`	boolean	`false`	Copy directories recursively.

Examples

# Copy a host file into the VM
lume cp ./build.zip my-vm:/tmp/build.zip
 
# Copy a file out of the VM
lume cp my-vm:/tmp/out.log ./out.log
 
# Copy a directory into the VM
lume cp -r ./assets my-vm:/tmp/assets

`lume sip`#

Enable or disable System Integrity Protection on a macOS VM.

Boots the stopped VM normally to validate the admin credentials, runs csrutil disable (or enable) in paired recoveryOS over VNC, then boots normally once more to verify the result. The VM needs an admin account and Remote Login; VMs from unattended setup use lume/lume. Prefer --admin-password-stdin: --admin-password is visible to other processes. Requires vncdotool (pip3 install vncdotool).

lume sip [OPTIONS] <state> <name>

Argument	Type	Default	Description
`<state>`	`on` \| `off`	required	Desired SIP state.
`<name>`	string	required	Name of the virtual machine.

Flag	Short	Type	Default	Description
`--admin-user`		string	`lume`	Administrator username in the guest.
`--admin-password`		string		Administrator password in the guest (default: lume); prefer --admin-password-stdin.
`--screenshot-dir`		string		Save step-by-step framebuffer PNGs here for debugging.
`--vnc-port`		integer	`5999`	TCP port for the temporary recovery VNC server.
`--storage`		string		VM storage location.
`--timeout`		integer	`900`	Overall timeout in seconds.
`--yes`	`-y`	boolean	`false`	Skip the interactive confirmation prompt.
`--admin-password-stdin`		boolean	`false`	Read one administrator-password line from standard input without echo.

Examples

lume sip off my-vm --yes
 
# With another admin account, password read from stdin
lume sip on my-vm --yes --admin-user alice --admin-password-stdin

Server#

Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions.

`lume serve`#

Start the VM management server.

Serves the HTTP API on localhost, or with --mcp an MCP server over stdio for AI agents.

lume serve [OPTIONS]

Flag	Type	Default	Description
`--port`	integer	`7777`	Port to listen on (HTTP mode only).
`--mcp`	boolean	`false`	Run as an MCP server (stdio transport) for AI agents.

Examples

# HTTP API on http://localhost:7777
lume serve
lume serve --port 7778
 
# MCP server over stdio (what MCP clients launch)
lume serve --mcp

`lume logs`#

View lume serve logs.

lume logs <COMMAND>

`lume logs info`#

View info logs from the daemon.

lume logs info [OPTIONS]

Flag	Short	Type	Default	Description
`--lines`	`-l`	integer		Number of lines to display from the end of the file.
`--follow`	`-f`	boolean	`false`	Follow the log continuously (like tail -f).

Examples

lume logs info --lines 100
lume logs info --follow

`lume logs error`#

View error logs from the daemon.

lume logs error [OPTIONS]

Flag	Short	Type	Default	Description
`--lines`	`-l`	integer		Number of lines to display from the end of the file.
`--follow`	`-f`	boolean	`false`	Follow the log continuously (like tail -f).

Examples

lume logs error --lines 100
lume logs error --follow

`lume logs all`#

View both info and error logs from the daemon.

lume logs all [OPTIONS]

Flag	Short	Type	Default	Description
`--lines`	`-l`	integer		Number of lines to display from the end of each file.
`--follow`	`-f`	boolean	`false`	Follow the log continuously (like tail -f).

Examples

lume logs all --lines 100
lume logs all --follow

`lume dump-docs`#

Output CLI and API documentation as JSON for tooling and integrations.

Emits the CLI, HTTP API or MCP tool metadata (arguments, options, flags, endpoints, tool schemas, help text, defaults and types) that the generated reference is built from.

lume dump-docs [OPTIONS]

Flag	Type	Default	Description
`--type`	`cli` \| `api` \| `mcp` \| `all`	`cli`	Documentation type to output.
`--pretty`	boolean	`false`	Pretty-print the JSON output with sorted keys.

Examples

lume dump-docs --type cli --pretty
 
# The MCP server's tool list
lume dump-docs --type mcp

Configuration#

Storage locations, the image cache and telemetry settings.

`lume config`#

Get or set lume configuration.

Without a subcommand, prints the current configuration (lume config get).

lume config <COMMAND>

`lume config get`#

Get current configuration.

lume config get

Examples

lume config get

`lume config storage`#

Manage VM storage locations.

lume config storage <COMMAND>

`lume config storage add`

Add a new VM storage location.

lume config storage add <name> <path>

Argument	Type	Default	Description
`<name>`	string	required	Storage name (letters, digits, dashes and underscores).
`<path>`	string	required	Path to the VM storage directory.

Examples

lume config storage add external /Volumes/External/lume

`lume config storage remove`

Remove a VM storage location.

lume config storage remove <name>

Argument	Type	Default	Description
`<name>`	string	required	Storage name to remove.

Examples

lume config storage remove external

`lume config storage list`

List all VM storage locations.

lume config storage list

Examples

lume config storage list

`lume config storage default`

Set the default VM storage location.

lume config storage default <name>

Argument	Type	Default	Description
`<name>`	string	required	Storage name to set as default.

Examples

lume config storage default external

`lume config cache`#

Manage image cache settings.

lume config cache <COMMAND>

`lume config cache dir`

Get or set cache directory.

lume config cache dir [<path>]

Argument	Type	Default	Description
`<path>`	string	optional	Path to the cache directory (omit to show the current one).

Examples

lume config cache dir
lume config cache dir /Volumes/External/lume-cache

`lume config cache enable`

Enable image caching.

lume config cache enable

Examples

lume config cache enable

`lume config cache disable`

Disable image caching.

lume config cache disable

Examples

lume config cache disable

`lume config cache status`

Show cache status and directory.

lume config cache status

Examples

lume config cache status

`lume config telemetry`#

Manage pseudonymous telemetry settings.

lume config telemetry <COMMAND>

`lume config telemetry status`

Show current telemetry status.

lume config telemetry status

Examples

lume config telemetry status

`lume config telemetry enable`

Enable pseudonymous telemetry.

lume config telemetry enable

Examples

lume config telemetry enable

`lume config telemetry disable`

Disable pseudonymous telemetry.

lume config telemetry disable

Examples

lume config telemetry disable

`lume config telemetry reset-id`

Delete the pseudonymous installation ID and registration markers.

lume config telemetry reset-id

Examples

lume config telemetry reset-id

`lume config registry`#

Manage container registry settings.

lume config registry <COMMAND>

`lume config registry status`

Show current registry configuration.

lume config registry status

Examples

lume config registry status

`lume config registry type`

Get or set registry type.

lume config registry type [<type>]

Argument	Type	Default	Description
`<type>`	string	optional	Registry type to use: ghcr or gcs (omit to show the current one).

Examples

lume config registry type
lume config registry type ghcr

`lume config registry ghcr`

Configure GitHub Container Registry settings.

lume config registry ghcr [OPTIONS]

Flag	Type	Default	Description
`--registry`	string		Registry URL (default: ghcr.io).
`--organization`	string		Organization or namespace (default: trycua).

Examples

lume config registry ghcr --organization my-org

`lume config registry gcs`

Configure GCS registry settings.

lume config registry gcs [OPTIONS]

Flag	Type	Default	Description
`--api-url`	string		API URL for signed URL generation.
`--api-key`	string		API key for authentication.

Examples

lume config registry gcs --api-url https://images.example.com --api-key <key>

`lume config network`#

Manage network settings.

lume config network <COMMAND>

`lume config network interfaces`

List available network interfaces for bridged networking.

lume config network interfaces

Examples

lume config network interfaces

Updates#

Check for, apply and choose the channel of Lume updates.

`lume check-update`#

Check whether a newer Lume release is available.

Read-only update check. Uses GitHub Releases, caches the result briefly, and never installs anything.

lume check-update [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	`false`	Emit the structured update-state payload as JSON.
`--no-cache`	boolean	`false`	Bypass the local update-check cache.

Examples

lume check-update
lume check-update --json --no-cache

`lume update`#

Check for a Lume update and optionally apply it.

Without --apply, this command only checks for a newer release and prints the command to install it. With --apply, it runs the official Lume installer pinned to the discovered version and exits with the installer's status.

lume update [OPTIONS]

Flag	Type	Default	Description
`--apply`	boolean	`false`	Apply the update while preserving the current background-service choice.
`--json`	boolean	`false`	Emit the structured update-state payload as JSON.

Examples

lume update
lume update --apply

`lume channel`#

Inspect or change the stable/nightly update channel; selection does not install.

The selection persists but never installs by itself; run lume update --apply after changing it. Without a subcommand, prints the status.

lume channel <COMMAND>

`lume channel status`#

Show selected and current release channels.

lume channel status [OPTIONS]

Flag	Type	Default	Description
`--json`	boolean	`false`	Emit machine-readable channel state as JSON.

Examples

lume channel status --json

`lume channel set`#

Save stable or nightly as the update channel.

lume channel set [OPTIONS] <channel>

Argument	Type	Default	Description
`<channel>`	string	required	Release channel: stable or nightly.

Flag	Type	Default	Description
`--json`	boolean	`false`	Emit machine-readable channel state as JSON.

Examples

lume channel set nightly
lume channel set stable

Global options#

--help prints help for any command; --version prints the version.

Exit codes#

Code	Meaning
`0`	Success.
`1`	The command failed (for example the VM does not exist or the operation errored).
`64`	Usage error: an unknown command or option, a missing argument, or an invalid value.

lume CLI

Commands#

VMs#

lume create#

lume run#

lume attach#

lume stop#

lume shutdown#

lume restart#

lume ls#

lume get#

lume set#

lume clone#

lume delete#

Images#

lume images#

lume pull#

lume push#

lume convert#

lume ipsw#

lume prune#

Guest access#

lume setup#

lume ssh#

lume cp#

lume sip#

Server#

lume serve#

lume logs#

lume logs info#

lume logs error#

lume logs all#

lume dump-docs#

Configuration#

lume config#

lume config get#

lume config storage#

lume config storage add

lume config storage remove

lume config storage list

lume config storage default

lume config cache#

lume config cache dir

lume config cache enable

lume config cache disable

lume config cache status

lume config telemetry#

lume config telemetry status

lume config telemetry enable

lume config telemetry disable

lume config telemetry reset-id

lume config registry#

lume config registry status

lume config registry type

lume config registry ghcr

lume config registry gcs

lume config network#

lume config network interfaces

Updates#

lume check-update#

lume update#

lume channel#

lume channel status#

lume channel set#

Global options#

Exit codes#

`lume create`#

`lume run`#

`lume attach`#

`lume stop`#

`lume shutdown`#

`lume restart`#

`lume ls`#

`lume get`#

`lume set`#

`lume clone`#

`lume delete`#

`lume images`#

`lume pull`#

`lume push`#

`lume convert`#

`lume ipsw`#

`lume prune`#

`lume setup`#

`lume ssh`#

`lume cp`#

`lume sip`#

`lume serve`#

`lume logs`#

`lume logs info`#

`lume logs error`#

`lume logs all`#

`lume dump-docs`#

`lume config`#

`lume config get`#

`lume config storage`#

`lume config storage add`

`lume config storage remove`

`lume config storage list`

`lume config storage default`

`lume config cache`#

`lume config cache dir`

`lume config cache enable`

`lume config cache disable`

`lume config cache status`

`lume config telemetry`#

`lume config telemetry status`

`lume config telemetry enable`

`lume config telemetry disable`

`lume config telemetry reset-id`

`lume config registry`#

`lume config registry status`

`lume config registry type`

`lume config registry ghcr`

`lume config registry gcs`

`lume config network`#

`lume config network interfaces`

`lume check-update`#

`lume update`#

`lume channel`#

`lume channel status`#

`lume channel set`#