Lume CLI Reference — VM Management Commands

Lume is a lightweight CLI and local API server for building, running, and managing macOS and Linux virtual machines on Apple Silicon. This page documents every command available in Lume. Documented against Lume 0.5.3. Run lume --version to check your installed version.

Install Lume before using these commands. See the Install Lume guide for instructions.

Global options

These options are available on every command:

Flag	Description
`--help`	Show help information for the command.
`--version`	Print the installed Lume version.

VM Management

`lume create`

Create a new virtual machine. Usage: lume create <name> [options]

<name>

string

required

Name to assign to the new virtual machine.

Options:

--os

string

default:"macOS"

Operating system to install. Accepts macOS or linux.

--cpu

int

default:"4"

Number of CPU cores to allocate.

--memory

string

default:"8GB"

Memory size. Accepts human-readable values such as 8GB or 16GB.

--disk-size

string

default:"100GB (macOS), 50GB (Linux)"

Disk size. Accepts values like 50GB or 200GB.

--display

string

default:"1024x768"

Display resolution, e.g. 1920x1080.

--ipsw

string

Path to an IPSW restore image, or 'latest' to download the latest compatible IPSW automatically (macOS VMs only).

--storage

string

Named VM storage location to use. Defaults to the configured default location.

--unattended

string

Prepare a macOS unattended (offline) setup after installation. Accepts a preset name (sequoia, tahoe) or a path to a YAML config. macOS only.

--vnc-port

int

default:"0"

Port for the temporary verification VNC server. 0 auto-assigns a port.

Flags:

--debug

boolean

default:"false"

Compatibility flag; ignored by offline setup.

--no-display

boolean

default:"false"

Compatibility flag; offline setup verifies headlessly.

`lume run`

Start and boot a virtual machine. Usage: lume run <name> [options]

<name>

string

required

Name of the VM or image to run. Accepts name or name:tag format.

--shared-dir

[string]

Directory path to share with the VM. Format: path, path:ro (read-only), or path:rw (read-write). May be specified multiple times.

--display

DisplayMode

default:"native"

Local viewer to open: native, vnc, or none. The VNC server is always available regardless of this setting.

--vnc-port

int

default:"0"

Port for the VNC server. 0 auto-assigns.

--recovery-mode

boolean

default:"false"

Boot in macOS recovery mode. macOS VMs only.

--storage

string

VM storage location to use.

--log-file

string

default:"~/Library/Logs/lume/{vm}.log"

Log path when running with --detach.

Flags:

-d, --no-display

boolean

default:"false"

Alias for --display none.

--detach

boolean

default:"false"

Run the VM in the background and return immediately.

--clipboard

boolean

default:"false"

Enable bidirectional clipboard sync via SSH. Enabled automatically with the native macOS display.

`lume attach`

Open a viewer for a VM that is already running. Usage: lume attach <name> [options]

<name>

string

required

Name of the running virtual machine.

--display

AttachDisplayMode

default:"native (VNC fallback)"

Viewer to open: native or vnc.

--storage

string

VM storage location.

`lume stop`

Stop a running virtual machine (hard stop). Usage: lume stop <name> [options]

<name>

string

required

Name of the VM to stop.

--storage

string

VM storage location.

`lume shutdown`

Gracefully shut down a virtual machine via SSH. Usage: lume shutdown <name> [options]

<name>

string

required

Name of the virtual machine.

-u, --user

string

default:"lume"

SSH username.

-p, --password

string

default:"lume"

SSH and sudo password.

-t, --timeout

int

default:"30"

SSH command timeout in seconds.

--storage

string

VM storage location.

`lume restart`

Gracefully restart a virtual machine via SSH. Usage: lume restart <name> [options] Parameters are identical to lume shutdown.

`lume delete`

Delete a virtual machine and all associated files. Usage: lume delete <name> [options]

<name>

string

required

Name of the VM to delete.

--storage

string

VM storage location.

--force

boolean

default:"false"

Skip the interactive confirmation prompt.

`lume clone`

Clone an existing virtual machine. Usage: lume clone <name> <new-name> [options]

<name>

string

required

Name of the source VM.

<new-name>

string

required

Name for the cloned VM.

--source-storage

string

Storage location of the source VM.

--dest-storage

string

Storage location for the cloned VM.

VM Information and Configuration

`lume ls`

List all virtual machines. Usage: lume ls [options]

-f, --format

string

default:"text"

Output format: text or json.

--storage

string

Filter by storage location name.

`lume get`

Get detailed information about a specific virtual machine. Usage: lume get <name> [options]

<name>

string

required

Name of the VM to inspect.

-f, --format

string

default:"text"

Output format: text or json.

--storage

string

VM storage location.

`lume set`

Update CPU, memory, disk size, or display resolution for a stopped VM. Usage: lume set <name> [options]

<name>

string

required

Name of the VM to update.

--cpu

int

New CPU core count.

--memory

string

New memory size, e.g. 16GB.

--disk-size

string

New total disk size (increase-only). macOS resizing preserves RecoveryOS and grows the APFS container.

--display

string

New display resolution.

--storage

string

VM storage location.

--no-backup

boolean

default:"false"

Skip the macOS rollback backup before resizing.

--keep-backup

boolean

default:"false"

Retain rollback files after a successful macOS resize.

--dry-run

boolean

default:"false"

Validate the resize plan without modifying the disk.

Image Management

`lume images`

List available VM images from the local cache. Usage: lume images [options]

--organization

string

default:"trycua"

Organization to list images for.

`lume pull`

Pull a prebuilt macOS or Linux image from an OCI-compatible registry. Usage: lume pull <image> [<name>] [options]

<image>

string

required

Image reference in name:tag format, e.g. macos-tahoe-vanilla:latest.

<name>

string

Optional name for the resulting local VM.

--registry

string

default:"ghcr.io"

Container registry URL.

--organization

string

default:"trycua"

Registry organization.

--storage

string

VM storage location.

`lume push`

Push a local VM to an OCI-compatible registry. Usage: lume push <name> <image> [options]

<name>

string

required

Name of the local VM to push.

<image>

string

required

Target image tag in name:tag format.

--registry

string

default:"ghcr.io"

Container registry URL.

--organization

string

default:"trycua"

Organization to push to.

--additional-tags

[string]

Extra tags to apply.

--chunk-size-mb

int

default:"512"

Upload chunk size in MB.

--storage

string

VM storage location.

--verbose

boolean

default:"false"

Enable verbose logging.

--dry-run

boolean

default:"false"

Prepare files without uploading.

--reassemble

boolean

default:"true"

Verify integrity by reassembling chunks after upload.

`lume ipsw`

Print the latest macOS restore image (IPSW) URL for the current hardware. Usage: lume ipsw

`lume prune`

Remove cached images to free up disk space. Usage: lume prune

`lume convert`

Convert a legacy Lume image to OCI-compliant format. Usage: lume convert <source-image> <target-image> [options]

<source-image>

string

required

Source image in legacy format, e.g. macos-tahoe:latest.

<target-image>

string

required

Target image name and tag in OCI format.

--registry

string

default:"ghcr.io"

Registry to pull from and push to.

--organization

string

default:"trycua"

Registry organization.

--additional-tags

[string]

Additional tags for the OCI image.

--verbose

boolean

default:"false"

Enable verbose logging.

--dry-run

boolean

default:"false"

Prepare without uploading.

--single-layer

boolean

default:"false"

Push one kubelet-compatible disk layer.

Guest Access and Security

`lume ssh`

Connect to a VM via SSH or execute a remote command. Usage: lume ssh <name> [<command>...] [options]

<name>

string

required

Name of the virtual machine.

[string]

Command to run. Omit for an interactive shell session.

-u, --user

string

default:"lume"

SSH username.

-p, --password

string

default:"lume"

SSH password.

-t, --timeout

int

default:"60"

Command timeout in seconds. 0 for no timeout.

--storage

string

VM storage location.

`lume setup`

Prepare an unattended macOS setup on a VM. Usage: lume setup <name> [options]

<name>

string

required

Name of the virtual machine.

--unattended

string

default:"tahoe"

Preset name (sequoia, tahoe) or path to a YAML config with optional post-SSH commands.

--vnc-port

int

default:"0"

Port for the temporary verification VNC server.

--storage

string

VM storage location.

`lume sip`

Enable or disable System Integrity Protection (SIP) on a macOS VM. Requires a stopped VM with Remote Login enabled. Usage: lume sip <state> <name> [options]

<state>

string

required

Desired SIP state: on or off.

<name>

string

required

Name of the virtual machine.

--admin-user

string

default:"lume"

Administrator username in the guest.

--admin-password

string

Administrator password. Prefer --admin-password-stdin.

--admin-password-stdin

boolean

default:"false"

Read the administrator password from stdin without echo.

--vnc-port

int

default:"5999"

Port for the temporary Recovery VNC server.

--timeout

int

default:"900"

Overall timeout in seconds.

--screenshot-dir

string

Directory for Recovery framebuffer screenshots.

--storage

string

VM storage location.

-y, --yes

boolean

default:"false"

Skip the confirmation prompt.

Configuration and Server

`lume serve`

Start the Lume HTTP API server, or run as an MCP stdio server. Usage: lume serve [options]

--port

int

default:"7777"

Port to listen on (HTTP mode only).

--mcp

boolean

default:"false"

Run as an MCP server over stdio for AI agent integration. When set, --port is ignored and the process communicates via stdin/stdout using the Model Context Protocol.

See the MCP Tools reference for the full list of tools exposed by lume serve --mcp.

`lume config`

Get or set Lume configuration. Subcommands:

Subcommand	Purpose
`lume config get`	Display the current configuration.
`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 storage locations.
`lume config storage default`	Set the default storage location.
`lume config cache status`	Show cache status and directory.
`lume config cache dir`	Get or set the cache directory.
`lume config cache enable`	Enable image caching.
`lume config cache disable`	Disable image caching.
`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.

`lume logs`

View Lume daemon logs.

Subcommand	Purpose
`lume logs info [-n N]`	View info logs (last N lines).
`lume logs error [-n N]`	View error logs (last N lines).
`lume logs all [-n N]`	View combined info and error logs.

`lume check-update`

Check whether a newer Lume release is available.

--json

boolean

default:"false"

Emit the structured update-state payload as JSON.

--no-cache

boolean

default:"false"

Bypass the local 20-hour update-check cache.

`lume update`

Check for and optionally apply a Lume update.

--apply

boolean

default:"false"

Apply the update by re-running the official installer.

--json

boolean

default:"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.

--type

string

default:"cli"

Documentation type to emit: cli, api, or all.

--pretty

boolean

default:"false"

Pretty-print the JSON output.

Cua Driver

Sandbox SDK

Lume

Cua Bench

Lume CLI Reference — VM Management Commands

Global options

VM Management

`lume create`

`lume run`

`lume attach`

`lume stop`

`lume shutdown`

`lume restart`

`lume delete`

`lume clone`

VM Information and Configuration

`lume ls`

`lume get`

`lume set`

Image Management

`lume images`

`lume pull`

`lume push`

`lume ipsw`

`lume prune`

`lume convert`

Guest Access and Security

`lume ssh`

`lume setup`

`lume sip`

Configuration and Server

`lume serve`

`lume config`

`lume logs`

`lume check-update`

`lume update`

Developer Tools

`lume dump-docs`

Build docs developers (and LLMs) love

Cua Driver

Sandbox SDK

Lume

Cua Bench

Documentation Index

​Global options

​VM Management

​lume create

​lume run

​lume attach

​lume stop

​lume shutdown

​lume restart

​lume delete

​lume clone

​VM Information and Configuration

​lume ls

​lume get

​lume set

​Image Management

​lume images

​lume pull

​lume push

​lume ipsw

​lume prune

​lume convert

​Guest Access and Security

​lume ssh

​lume setup

​lume sip

​Configuration and Server

​lume serve

​lume config

​lume logs

​lume check-update

​lume update

​Developer Tools

​lume dump-docs

Build docs developers (and LLMs) love

Global options

VM Management

`lume create`

`lume run`

`lume attach`

`lume stop`

`lume shutdown`

`lume restart`

`lume delete`

`lume clone`

VM Information and Configuration

`lume ls`

`lume get`

`lume set`

Image Management

`lume images`

`lume pull`

`lume push`

`lume ipsw`

`lume prune`

`lume convert`

Guest Access and Security

`lume ssh`

`lume setup`

`lume sip`

Configuration and Server

`lume serve`

`lume config`

`lume logs`

`lume check-update`

`lume update`

Developer Tools

`lume dump-docs`