VMs

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

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.

Every command also accepts the global options.

`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

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.

VMs

lume create#

lume run#

lume attach#

lume stop#

lume shutdown#

lume restart#

lume ls#

lume get#

lume set#

lume clone#

lume delete#

Exit codes#

lume create#

lume run#

lume attach#

lume stop#

lume shutdown#

lume restart#

lume ls#

lume get#

lume set#

lume clone#

lume delete#

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 create`#

`lume run`#

`lume attach`#

`lume stop`#

`lume shutdown`#

`lume restart`#

`lume ls`#

`lume get`#

`lume set`#

`lume clone`#

`lume delete`#