From 7814ea297cdbd10271152eeb72ef4f707092aa84 Mon Sep 17 00:00:00 2001 From: James Murdza Date: Wed, 27 Aug 2025 21:21:39 -0400 Subject: [PATCH] Extend CLI Reference --- .../docs/libraries/lume/cli-reference.mdx | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) diff --git a/docs/content/docs/libraries/lume/cli-reference.mdx b/docs/content/docs/libraries/lume/cli-reference.mdx index 8c4b2c61..f532c1a1 100644 --- a/docs/content/docs/libraries/lume/cli-reference.mdx +++ b/docs/content/docs/libraries/lume/cli-reference.mdx @@ -34,3 +34,176 @@ lume create my-linux-vm --os linux --cpu 2 --memory 4GB 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 --disk-size `. + +## VM Management + + lume create <name> +Create a new macOS or Linux virtual machine. + +**Options:** +- `--os ` - Operating system to install (macOS or linux, default: macOS) +- `--cpu ` - Number of CPU cores (default: 4) +- `--memory ` - Memory size, e.g., 8GB (default: 4GB) +- `--disk-size ` - Disk size, e.g., 50GB (default: 40GB) +- `--display ` - Display resolution (default: 1024x768) +- `--ipsw ` - Path to IPSW file or 'latest' for macOS VMs +- `--storage ` - 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 <name> +Start and run a virtual machine. + +**Options:** +- `--no-display` - Do not start the VNC client app +- `--shared-dir ` - Share directory with VM (format: path[:ro|rw]) +- `--mount ` - For Linux VMs only, attach a read-only disk image +- `--registry ` - Container registry URL (default: ghcr.io) +- `--organization ` - Organization to pull from (default: trycua) +- `--vnc-port ` - Port to use for the VNC server (default: 0 for auto-assign) +- `--recovery-mode ` - For macOS VMs only, start VM in recovery mode (default: false) +- `--storage ` - 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 <name> +Stop a running virtual machine. + +**Options:** +- `--storage ` - VM storage location to use + +### lume delete <name> +Delete a virtual machine and its associated files. + +**Options:** +- `--force` - Force deletion without confirmation +- `--storage ` - VM storage location to use + +### lume clone <name> <new-name> +Create a copy of an existing virtual machine. + +**Options:** +- `--source-storage ` - Source VM storage location +- `--dest-storage ` - Destination VM storage location + +## VM Information and Configuration + +### lume ls +List all virtual machines and their status. + +### lume get <name> +Get detailed information about a specific virtual machine. + +**Options:** +- `-f, --format ` - Output format (json|text) +- `--storage ` - VM storage location to use + +### lume set <name> +Modify virtual machine configuration. + +**Options:** +- `--cpu ` - New number of CPU cores (e.g., 4) +- `--memory ` - New memory size (e.g., 8192MB or 8GB) +- `--disk-size ` - New disk size (e.g., 40960MB or 40GB) +- `--display ` - New display resolution in format WIDTHxHEIGHT (e.g., 1024x768) +- `--storage ` - 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 <image> +Download a VM image from a container registry. + +**Options:** +- `--registry ` - Container registry URL (default: ghcr.io) +- `--organization ` - Organization to pull from (default: trycua) +- `--storage ` - VM storage location to use + +### lume push <name> <image:tag> +Upload a VM image to a container registry. + +**Options:** +- `--additional-tags ` - Additional tags to push the same image to +- `--registry ` - Container registry URL (default: ghcr.io) +- `--organization ` - Organization/user to push to (default: trycua) +- `--storage ` - VM storage location to use +- `--chunk-size-mb ` - 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 ` - 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 + +##### Cache Management +- `lume config cache get` - Get current cache directory +- `lume config cache set ` - Set cache directory + +##### Image Caching +- `lume config caching get` - Show current caching status +- `lume config caching set ` - Enable or disable image caching + +## API Server + +### lume serve +Start the Lume API server for programmatic access. + +**Options:** +- `--port ` - Port to listen on (default: 7777) + +## Global Options + +These options are available for all commands: + +- `--help` - Show help information +- `--version` - Show version number \ No newline at end of file