Images
Pull, push and convert VM images, find restore images, and prune the cache.
Pull, push and convert VM images, find restore images, and prune the cache.
| Command | Description |
|---|---|
lume images | List available macOS images from local cache. |
lume pull | Pull a prebuilt or custom macOS image from an OCI-compatible registry. |
lume push | Push a macOS VM to an OCI-compatible registry. |
lume convert | Convert a legacy Lume image to OCI-compliant format. |
lume ipsw | Get macOS restore image IPSW URL. |
lume prune | Remove cached images. |
Every command also accepts the global options.
lume images#List available macOS images from local cache.
lume images [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--organization | string | trycua | Organization to list images for. |
Examples
lume imageslume pull#Pull a prebuilt or custom macOS image from an OCI-compatible registry.
lume pull [OPTIONS] <image> [<name>]| Argument | Type | Default | Description |
|---|---|---|---|
<image> | string | required | Image to pull (format: name:tag). |
<name> | string | optional | Name for the resulting VM (defaults to the image name without its tag). |
| Flag | Type | Default | Description |
|---|---|---|---|
--registry | string | ghcr.io | Container registry to pull from. |
--organization | string | trycua | Organization to pull from. |
--storage | string | VM storage location name, or a direct path to the VM location. | |
--username | string | Registry username for authentication. | |
--password | string | Registry password for authentication. | |
--force | boolean | false | Download again even if the image is cached. |
--verbose | boolean | false | Enable verbose logging. |
Examples
# Pull an image from ghcr.io/trycua as a VM named macos-tahoe-vanilla
lume pull macos-tahoe-vanilla:latest
# Pull it as my-vm into another storage location
lume pull macos-tahoe-vanilla:latest my-vm --storage externallume push#Push a macOS VM to an OCI-compatible registry.
lume push [OPTIONS] <name> <image>| Argument | Type | Default | Description |
|---|---|---|---|
<name> | string | required | Name of the VM to push. |
<image> | string | required | Image tag to push (format: name:tag). |
| Flag | Type | Default | Description |
|---|---|---|---|
--additional-tags | string | Additional tags to push the same image to. Takes one or more values. | |
--registry | string | ghcr.io | Container registry to push to. |
--organization | string | trycua | Organization to push to. |
--storage | string | VM storage location to use. | |
--chunk-size-mb | integer | 512 | Chunk size for large files, in MB. |
--verbose | boolean | false | Enable verbose logging. |
--dry-run | boolean | false | Prepare files without uploading to the registry. |
--reassemble | boolean | false | With --dry-run, also reassemble the chunks to verify integrity. |
--single-layer | boolean | false | Push the disk as a single layer (kubelet-compatible, no chunking). |
--legacy | boolean | false | Use the legacy Lume LZ4-chunked format instead of the OCI-compliant format. |
Examples
# Push my-vm as ghcr.io/my-org/my-image:latest
lume push my-vm my-image:latest --organization my-org
# Push one image under several tags
lume push my-vm my-image:1.0 --additional-tags latest stable
# Prepare and verify the chunks without uploading
lume push my-vm my-image:latest --dry-run --reassemblelume convert#Convert a legacy Lume image to OCI-compliant format.
Pulls a legacy Lume image from the registry, pushes it again in OCI-compliant format under a new name and tag, then removes the temporary local VM.
lume convert [OPTIONS] <source-image> <target-image>| Argument | Type | Default | Description |
|---|---|---|---|
<source-image> | string | required | Source image to convert (legacy format, for example macos-tahoe:latest). |
<target-image> | string | required | Target image to push in OCI format (format: name:tag). |
| Flag | Type | Default | Description |
|---|---|---|---|
--additional-tags | string | Additional tags to push the OCI image to. Takes one or more values. | |
--registry | string | ghcr.io | Registry to pull from and push to. |
--organization | string | trycua | Registry organization. |
--verbose | boolean | false | Enable verbose logging. |
--dry-run | boolean | false | Prepare files without uploading to the registry. |
--single-layer | boolean | false | Push the disk as a single layer (kubelet-compatible, no chunking). |
Examples
lume convert macos-tahoe:latest macos-tahoe:latest-ocilume ipsw#Get macOS restore image IPSW URL.
Prints the URL of the latest supported restore image. Download it, then pass the file to lume create --ipsw.
lume ipswExamples
lume ipswlume prune#Remove cached images.
lume pruneExamples
lume prune| 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. |