Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Merge remote-tracking branch 'origin/main' into docs/restore-lume-p0

Francesco Bonacci2dd7d06cb1a4
diff --cc docs/content/docs/how-to-guides/lume/install-lume.mdx
index be13e8717e,230786d7a4..ae0aa8756e
--- a/docs/content/docs/how-to-guides/lume/install-lume.mdx
+++ b/docs/content/docs/how-to-guides/lume/install-lume.mdx
@@@ -34,24 -22,26 +22,43 @@@ Install with a single command
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
+ ## Verify the install
+
+ ```bash
+ lume --version
+ ```
+
+## Update Lume
+
+Check whether a newer release is available:
+
+```bash
+lume check-update
+```
+
+Apply an available update:
+
+```bash
+lume update --apply
+```
+
+The installer no longer creates scheduled auto-updaters. Older `lume-update` cron jobs and
+LaunchAgents are removed the next time the installer runs.
+
- ### Manual Start (No Background Service)
+ ## Run a prebuilt VM
+
+ Pull and start a prebuilt macOS image:
+
+ ```bash
+ lume run macos-sequoia-vanilla:latest
+ ```
+
+ <Callout title="Security Note">
+ Prebuilt images use the default password `lume`. Change this immediately after your first login
+ using the `passwd` command.
+ </Callout>
+
+ ## Start the API service manually
By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:
diff --cc docs/content/docs/reference/lume/cli-reference.mdx
index 0000000000,c13bfcaa79..fdaad4c50b
mode 000000,100644..100644
--- a/docs/content/docs/reference/lume/cli-reference.mdx
+++ b/docs/content/docs/reference/lume/cli-reference.mdx
@@@ -1,0 -1,352 +1,368 @@@
+ ---
+ title: CLI Reference
+ description: Command Line Interface reference for Lume
+ ---
+
+ {/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/lume.ts
+ Source: lume dump-docs --type cli
+ Version: 0.3.10
+ */}
+
+ A lightweight CLI and local API server to build, run and manage macOS VMs.
+
+ Documented against Lume **0.3.10**. Run `lume --version` for your installed version.
+
+ For installation steps, see [Install Lume](/how-to-guides/lume/install-lume).
+
++## Update Lume
++
++```bash
++# Check whether a newer release is available
++lume check-update
++
++# Apply an available update
++lume update --apply
++```
++
++`lume check-update --json` returns the current version, latest version, update availability,
++release notes URL, and install command. `lume update` only applies an update when `--apply` is
++provided.
++
++The MCP server also exposes a read-only `check_for_update` tool with the same update-state payload.
++
+ ## 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 | 50GB | Disk size (e.g., 50GB) |
+ | `--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 | - | [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs. |
+ | `--debug-dir` | String | - | Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp) |
+ | `--vnc-port` | Int | 0 | Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign) |
+
+ **Flags:**
+
+ | Name | Default | Description |
+ | ---- | ------- | ----------- |
+ | `--debug` | false | Enable debug mode for unattended setup - saves screenshots with click coordinates |
+ | `--no-display` | false | Do not open the VNC client during unattended setup (default: true for unattended) |
+
+ ### 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 |
+
+ ### 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 |
+
+ ## VM Information and Configuration
+
+ ### 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 disk size (e.g., 100GB) |
+ | `--display` | String | - | New display resolution |
+ | `--storage` | String | - | VM storage location to use |
+
+ ### 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 |
+
+ ## Image Management
+
+ ### lume pull
+
+ Pull a macOS image from GitHub Container 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 GitHub Container 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 images
+
+ List available macOS images from local cache
+
+ **Options:**
+
+ | Name | Type | Default | Description |
+ | ---- | ---- | ------- | ----------- |
+ | `--organization` | String | trycua | Organization to list images for |
+
+ ### lume ipsw
+
+ Get macOS restore image IPSW URL
+
+ ### lume prune
+
+ Remove cached images
+
+ ## Guest Access and Setup
+
+ ### 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
+
+ [Preview] Run unattended Setup Assistant automation on a macOS VM
+
+ **Arguments:**
+
+ | Name | Type | Required | Description |
+ | ---- | ---- | -------- | ----------- |
+ | `<name>` | String | Yes | Name of the virtual machine |
+
+ **Options:**
+
+ | Name | Type | Default | Description |
+ | ---- | ---- | ------- | ----------- |
+ | `--unattended` | String | - | Preset name or path to YAML config file for unattended macOS Setup Assistant automation. 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 VNC server. Defaults to 0 (auto-assign) |
+ | `--debug-dir` | String | - | Custom directory for debug screenshots (defaults to unique folder in system temp) |
+
+ **Flags:**
+
+ | Name | Default | Description |
+ | ---- | ------- | ----------- |
+ | `--no-display` | false | Do not open the VNC client automatically |
+ | `--debug` | false | Enable debug mode - saves screenshots with click coordinates |
+
+ ## Configuration and Server
+
+ ### lume serve
+
+ Start the VM management server
+
+ **Options:**
+
+ | Name | Type | Default | Description |
+ | ---- | ---- | ------- | ----------- |
+ | `--port` | Int | 7777 | Port to listen on |
+
+ ### 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 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
+
+ ## Global Options
+
+ These options are available for all commands:
+
+ - `--help` - Show help information
+ - `--version` - Show version number
diff --cc scripts/docs-generators/lume.ts
index 109baa5888,f6828fded3..6142a1b3cd
--- a/scripts/docs-generators/lume.ts
+++ b/scripts/docs-generators/lume.ts
@@@ -351,7 -327,8 +327,8 @@@ export function generateCLIReferenceMDX
const vmManagement = ['create', 'run', 'stop', 'delete', 'clone'];
const vmInfo = ['ls', 'get', 'set'];
const imageManagement = ['images', 'pull', 'push', 'ipsw', 'prune'];
- const configuration = ['config', 'serve', 'logs', 'setup', 'check-update', 'update'];
+ const guestAccess = ['ssh', 'setup'];
- const configuration = ['config', 'serve', 'logs'];
++ const configuration = ['config', 'serve', 'logs', 'check-update', 'update'];
lines.push('## VM Management');
lines.push('');