---
title: Lume CLI Reference
description: Command Line Interface reference for Lume
---

import { Callout } from 'fumadocs-ui/components/callout';

Once installed, you can start using Lume with these common workflows:

### Run a Prebuilt VM

```bash
# Run a macOS Sequoia VM
lume run macos-sequoia-vanilla:latest

# Run an Ubuntu VM
lume run ubuntu-noble-vanilla:latest
```

<Callout>
  We provide [prebuilt VM images](../lume/prebuilt-images) in our [ghcr
  registry](https://github.com/orgs/trycua/packages).
</Callout>

### Create a Custom VM

```bash
# Create a new macOS VM
lume create my-macos-vm --cpu 4 --memory 8GB --disk-size 50GB

# Create a Linux VM
lume create my-linux-vm --os linux --cpu 2 --memory 4GB
```

<Callout title="Disk Space">
The actual disk space used by sparse images will be much lower than the logical size listed. You can resize VM disks after creation using `lume set <name> --disk-size <size>`.
</Callout>

## VM Management

lume create &lt;name&gt;
Create a new macOS or Linux virtual machine.

**Options:**

- `--os <os>` - Operating system to install (macOS or linux, default: macOS)
- `--cpu <cores>` - Number of CPU cores (default: 4)
- `--memory <size>` - Memory size, e.g., 8GB (default: 4GB)
- `--disk-size <size>` - Disk size, e.g., 50GB (default: 40GB)
- `--display <res>` - Display resolution (default: 1024x768)
- `--ipsw <path>` - Path to IPSW file or 'latest' for macOS VMs
- `--storage <name>` - VM storage location to use

**Examples:**

```bash
# Create macOS VM with custom specs
lume create my-mac --cpu 6 --memory 16GB --disk-size 100GB

# Create Linux VM
lume create my-ubuntu --os linux --cpu 2 --memory 8GB

# Create macOS VM with latest IPSW
lume create my-sequoia --ipsw latest
```

lume run &lt;name&gt;
Start and run a virtual machine.

**Options:**

- `--no-display` - Do not start the VNC client app
- `--shared-dir <dir>` - Share directory with VM (format: path[:ro|rw])
- `--mount <path>` - For Linux VMs only, attach a read-only disk image
- `--registry <url>` - Container registry URL (default: ghcr.io)
- `--organization <org>` - Organization to pull from (default: trycua)
- `--vnc-port <port>` - Port to use for the VNC server (default: 0 for auto-assign)
- `--recovery-mode <boolean>` - For macOS VMs only, start VM in recovery mode (default: false)
- `--storage <name>` - VM storage location to use

**Examples:**

```bash
# Run VM with shared directory
lume run my-vm --shared-dir /path/to/share:rw

# Run VM without display (headless)
lume run my-vm --no-display

# Run macOS VM in recovery mode
lume run my-mac --recovery-mode true
```

lume stop &lt;name&gt;
Stop a running virtual machine.

**Options:**

- `--storage <name>` - VM storage location to use

### lume delete &lt;name&gt;

Delete a virtual machine and its associated files.

**Options:**

- `--force` - Force deletion without confirmation
- `--storage <name>` - VM storage location to use

### lume clone &lt;name&gt; &lt;new-name&gt;

Create a copy of an existing virtual machine.

**Options:**

- `--source-storage <name>` - Source VM storage location
- `--dest-storage <name>` - Destination VM storage location

## VM Information and Configuration

### lume ls

List all virtual machines and their status.

### lume get &lt;name&gt;

Get detailed information about a specific virtual machine.

**Options:**

- `-f, --format <format>` - Output format (json|text)
- `--storage <name>` - VM storage location to use

### lume set &lt;name&gt;

Modify virtual machine configuration.

**Options:**

- `--cpu <cores>` - New number of CPU cores (e.g., 4)
- `--memory <size>` - New memory size (e.g., 8192MB or 8GB)
- `--disk-size <size>` - New disk size (e.g., 40960MB or 40GB)
- `--display <res>` - New display resolution in format WIDTHxHEIGHT (e.g., 1024x768)
- `--storage <name>` - VM storage location to use

**Examples:**

```bash
# Increase VM memory
lume set my-vm --memory 16GB

# Change display resolution
lume set my-vm --display 1920x1080

# Add more CPU cores
lume set my-vm --cpu 8
```

## Image Management

### lume images

List available macOS images in local cache.

### lume pull &lt;image&gt;

Download a VM image from a container registry.

**Options:**

- `--registry <url>` - Container registry URL (default: ghcr.io)
- `--organization <org>` - Organization to pull from (default: trycua)
- `--storage <name>` - VM storage location to use

### lume push &lt;name&gt; &lt;image:tag&gt;

Upload a VM image to a container registry.

**Options:**

- `--additional-tags <tags...>` - Additional tags to push the same image to
- `--registry <url>` - Container registry URL (default: ghcr.io)
- `--organization <org>` - Organization/user to push to (default: trycua)
- `--storage <name>` - VM storage location to use
- `--chunk-size-mb <size>` - Chunk size for disk image upload in MB (default: 512)
- `--verbose` - Enable verbose logging
- `--dry-run` - Prepare files and show plan without uploading
- `--reassemble` - Verify integrity by reassembling chunks (requires --dry-run)

### lume ipsw

Get the latest macOS restore image URL.

### lume prune

Remove cached images to free up disk space.

## Configuration

### lume config

Manage Lume configuration settings.

**Subcommands:**

##### Storage Management

- `lume config storage add <name> <path>` - Add a new VM storage location
- `lume config storage remove <name>` - Remove a VM storage location
- `lume config storage list` - List all VM storage locations
- `lume config storage default <name>` - Set the default VM storage location

##### Cache Management

- `lume config cache get` - Get current cache directory
- `lume config cache set <path>` - Set cache directory

##### Image Caching

- `lume config caching get` - Show current caching status
- `lume config caching set <boolean>` - Enable or disable image caching

## API Server

### lume serve

Start the Lume API server for programmatic access.

**Options:**

- `--port <port>` - Port to listen on (default: 7777)

## Global Options

These options are available for all commands:

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