cua image
Pull, build and push OCI images, and manage Fleet image resources; list the image catalog.
Pull, build and push OCI images, and manage Fleet image resources; list the image catalog.
| Command | Description |
|---|---|
cua image | Images: local OCI pull/build/push and Fleet image resources. |
cua image pull | Pull an image into the local cache. |
cua image build | Build an image from an images.cua.ai/v1alpha1 Image resource (JSON). |
cua image push | Copy an image (host architecture) to another registry reference. |
cua image ls | List Fleet image resources. |
cua image info | Show a Fleet image resource. |
cua image rm | Delete a Fleet image resource. |
cua image create | Submit an Image manifest (JSON) to Fleet for a remote build. |
cua images | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. |
cua images ls | List the catalog: ref, OS, container or VM, local and cloud runtime, cua-spacesd, browsers, summary. |
cua images info | Show one catalog entry (a ref or an alias such as linux). |
cua images build | Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk. |
cua images pack | Pack the disks cua images build --outputs disk wrote as KubeVirt containerDisks <repo>:<tag>-<arch> (push, or load into docker). |
cua images publish | Publish a built image as immutable pins <series>-<stamp> and <series>-disk-<stamp>, refusing any that exist. |
cua images release | Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. |
cua images promote | Move a series' moving tags (edge, edge-disk) to the pins a cua images publish record names, after the gates passed. |
Every command also accepts the global options.
cua image#Images: local OCI pull/build/push and Fleet image resources.
cua image [OPTIONS] <COMMAND>Alias: cua img.
cua image pull#Pull an image into the local cache.
cua image pull [OPTIONS] <REFERENCE>| Argument | Type | Default | Description |
|---|---|---|---|
<REFERENCE> | string | required | Image reference or alias. |
Examples
cua image pull linux
cua image pull ghcr.io/trycua/linux:24.04cua image build#Build an image from an images.cua.ai/v1alpha1 Image resource (JSON).
cua image build [OPTIONS] --base <BASE> <SPEC>| Argument | Type | Default | Description |
|---|---|---|---|
<SPEC> | path | required | Image resource file (JSON). |
| Flag | Type | Default | Description |
|---|---|---|---|
--base | string | required | Base image (container:<ref>, vm:<ref>, disk:<path>). |
--push | string | Push the result to this reference. |
Examples
cua image build image.json --base container:ubuntu:24.04
cua image build image.json --base container:ubuntu:24.04 --push ghcr.io/acme/desktop:1cua image push#Copy an image (host architecture) to another registry reference.
cua image push [OPTIONS] <REFERENCE> <DESTINATION>| Argument | Type | Default | Description |
|---|---|---|---|
<REFERENCE> | string | required | Source image reference or alias. |
<DESTINATION> | string | required | Destination registry reference. |
Examples
cua image push linux ghcr.io/acme/desktop:1cua image ls#List Fleet image resources.
cua image ls [OPTIONS]Alias: cua image list.
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace | string | Namespace (default: every namespace, or CUA_FLEET_NAMESPACE). |
Examples
cua image ls
cua image ls --namespace acmecua image info#Show a Fleet image resource.
cua image info [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Image resource name. |
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace | string | Namespace (default: CUA_FLEET_NAMESPACE). |
Examples
cua image info desktopcua image rm#Delete a Fleet image resource.
cua image rm [OPTIONS] <NAME>Alias: cua image delete.
| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Image resource name. |
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace | string | Namespace (default: CUA_FLEET_NAMESPACE). | |
--force | boolean | false | Do not ask for confirmation. |
Examples
cua image rm desktopcua image create#Submit an Image manifest (JSON) to Fleet for a remote build.
cua image create [OPTIONS] --file <FILE>| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--file | -f | path | required | Image manifest file (JSON). |
--namespace | string | Namespace (default: CUA_FLEET_NAMESPACE). |
Examples
cua image create -f image.jsoncua images#The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser.
cua images [OPTIONS] <COMMAND>cua images ls#List the catalog: ref, OS, container or VM, local and cloud runtime, cua-spacesd, browsers, summary.
cua images ls [OPTIONS]Alias: cua images list.
| Flag | Type | Default | Description |
|---|---|---|---|
--os | string | Only this OS: linux, windows or macos. | |
--all | boolean | false | Include unpublished entries (benchmark images). |
--browser | boolean | false | Only images with a browser the cua-driver browser tools drive. |
Examples
cua images ls
# Images whose browser the cua-driver browser tools drive
cua images ls --browser
cua images ls --all --jsoncua images info#Show one catalog entry (a ref or an alias such as linux).
cua images info [OPTIONS] <REFERENCE>| Argument | Type | Default | Description |
|---|---|---|---|
<REFERENCE> | string | required | Image ref or alias. |
Examples
cua images info linuxcua images build#Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk.
Outputs: rootfs <repo>:docker-<tag>-<arch>; disk <out>/<name>/<arch>/disk.img; containerdisk <repo>:<tag>-<arch>. --push pushes the outputs the image.json lists (a VM-only image never pushes its rootfs).
cua images build [OPTIONS] <DIR>| Argument | Type | Default | Description |
|---|---|---|---|
<DIR> | path | required | Image definition directory (Dockerfile, image.json). |
| Flag | Type | Default | Description |
|---|---|---|---|
--platform | string | Platforms, comma separated (default: the host's, or the image's only one). | |
--tag | string | local | Tag for the per-arch outputs. |
--repo | string | Repository (default: image.json repository, else cua-e2e-local/<name>). | |
--outputs | string | rootfs | Outputs: rootfs, disk, containerdisk (comma separated). |
--build-arg | string | Docker build argument KEY=VALUE (repeatable). | |
--build-context | string | Named build context NAME=PATH (repeatable). | |
--label | string | Extra rootfs label KEY=VALUE (repeatable). | |
--out | path | Where disks go (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). | |
--disk-size | string | 20G | Virtual size of the disk. |
--target | string | Dockerfile stage to build (a tier: slim, full); disks go to <out>/<name>-<target>/<arch>. Default: the Dockerfile's last stage. | |
--push | boolean | false | Push the published outputs. |
--dry-run | boolean | false | Print the steps without running them. |
Examples
cua images build libs/images/omarchy --outputs rootfs,disk
cua images build libs/images/omarchy --tag build-1a2b3c4d --outputs containerdisk --push
cua images build libs/images/linux --target slim --tag 24.04-slim-local --outputs rootfs,disk
cua images build libs/images/linux --platform linux/amd64,linux/arm64 --dry-runcua images pack#Pack the disks cua images build --outputs disk wrote as KubeVirt containerDisks <repo>:<tag>-<arch> (push, or load into docker).
Packs exactly the disk the doctor checked, so the pushed bytes are the tested ones.
cua images pack [OPTIONS] <DIR>| Argument | Type | Default | Description |
|---|---|---|---|
<DIR> | path | required | Image definition directory. |
| Flag | Type | Default | Description |
|---|---|---|---|
--platform | string | Platforms, comma separated (default: the host's, or the image's only one). | |
--tag | string | local | Tag for the per-arch containerDisks. |
--repo | string | Repository (default: image.json repository, else cua-e2e-local/<name>). | |
--out | path | Where the disks are (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). | |
--target | string | The --target the disks were built with (their <name>-<target> dir). | |
--push | boolean | false | Push instead of loading into docker. |
--dry-run | boolean | false | Print what would be packed. |
Examples
cua images pack libs/images/omarchy --tag ci-1a2b3c4d --push --jsoncua images publish#Publish a built image as immutable pins <series>-<stamp> and <series>-disk-<stamp>, refusing any that exist. Moves nothing.
Reads the per-arch images cua images build --tag TAG --push wrote
(<repo>:<tag>-<arch>, and <repo>:docker-<tag>-<arch> when the image has a rootfs
output). Writes the record cua images promote takes.
cua images publish [OPTIONS] --tag <TAG> --series <SERIES> <DIR>| Argument | Type | Default | Description |
|---|---|---|---|
<DIR> | path | required | Image definition directory. |
| Flag | Type | Default | Description |
|---|---|---|---|
--tag | string | required | The build tag the per-arch images were pushed under. |
--series | string | required | Series / channel (edge, 24.04). |
--stamp | string | Pin stamp <yyyymmdd>-<sha7> (default: today and git HEAD). | |
--repo | string | Repository (default: image.json repository). | |
--platform | string | Platforms (default: image.json platforms). | |
--annotation | string | Extra index annotation KEY=VALUE (repeatable). | |
--descriptor-annotation | string | Annotation on one child's descriptor, VARIANT/ARCH:KEY=VALUE (rootfs/amd64:ai.cua.doctor.status=pass; repeatable). | |
--record | path | Write the publish record (JSON) here. | |
--dry-run | boolean | false | Resolve and print, push nothing. |
Examples
cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --record pins.json
cua images publish libs/images/linux --tag build-20260925-1a2b3c4 --series 24.04 --descriptor-annotation rootfs/amd64:ai.cua.doctor.status=pass
cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --dry-runcua images release#Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. The same command runs locally and in CI.
Phases: prepare, build, gate (doctor lanes), stage, push, publish, verify, promote. Push refuses unless every required gate passed (this run, or a state-*.json merged from other jobs in <work>/evidence). Evidence, logs and the summary go to <work>/evidence (a plain directory CI uploads as-is).
cua images release [OPTIONS] <DIR>| Argument | Type | Default | Description |
|---|---|---|---|
<DIR> | path | required | Image directory with a release.json. |
| Flag | Type | Default | Description |
|---|---|---|---|
--tier | string | Tier (slim, full) for images that have tiers. | |
--arch | string | Arches, comma separated (default: release.json arches). Repeatable. | |
--stamp | string | Pin stamp <yyyymmdd>-<sha7> (default: today and git HEAD). | |
--work | path | Work directory (default: $CUA_RELEASE_WORK, else under the cua build cache, which cua cache prune manages). | |
--steps | string | Only these steps: phase names or step-id prefixes (comma separated). Repeatable. | |
--from | string | Rerun from this phase or step; the steps before it must have passed. | |
--var | string | Variable KEY=VALUE for release.json templates (repeatable). | |
--assume | string | Treat a host capability as present (kvm) or absent (!runsc). Repeatable. | |
--scope | string | This run's state file name, state-<scope>.json (default: the arches); CI jobs sharing an evidence directory use distinct scopes. | |
--resume | boolean | false | Skip steps that passed with the same inputs and whose outputs exist. |
--dry-run | boolean | false | Print the plan; run nothing. |
--publish | boolean | false | Also push, publish immutable pins and verify them. |
--promote | boolean | false | Also move the floating tags to the pins. |
Examples
# Plan only
cua images release libs/images/linux --tier slim --dry-run
# Build and doctor amd64 locally; resume after a failure
cua images release libs/images/linux --tier slim --arch amd64 --resume
# Rerun from the doctor lanes (the build must have passed)
cua images release libs/images/linux --tier slim --from gate
# One CI job's slice
cua images release libs/images/linux --tier full --arch arm64 --steps build,gate,stage --work release
# Publish and promote (the gates must have passed)
cua images release libs/images/omarchy --publish --promote --resumecua images promote#Move a series' moving tags (edge, edge-disk) to the pins a cua images publish record names, after the gates passed.
cua images promote [OPTIONS] <RECORD>| Argument | Type | Default | Description |
|---|---|---|---|
<RECORD> | path | required | Record written by cua images publish --record. |
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | boolean | false | Check and print, move nothing. |
Examples
cua images promote pins.json
cua images promote pins.json --dry-run| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, or cua do reported an error. |
2 | Invalid argument, or an ambiguous sandbox name (qualify it: local:NAME, cloud:NAME). |
3 | Not found: sandbox, window, skill or image (or an image not published yet). |
4 | Not supported, or not configured (for example no Fleet credentials). |
5 | No cua-spacesd answered, or a transport failure. |
6 | Unauthenticated or permission denied (by Cua, Fleet or your cloud account). |
7 | Not enough free disk space (see cua cache). |
130 | Cancelled (Ctrl-C during a create): what it made was removed. |