Command Reference

Package: cua-cli | Install: pip install cua-cli

Command Groups

Group	Alias	Description
`cua sandbox`	`cua sb`	Sandbox lifecycle management
`cua auth`		Authentication
`cua image`	`cua img`	Local image management
`cua skills`		Skills recording and playback
`cua serve-mcp`		Start MCP server

Sandbox Commands

All sandbox commands support the cua sb alias (e.g. cua sb launch).

`cua sb launch <image>`

Launch a new sandbox. The image is a positional argument; resource specs are options.

cua sb launch ubuntu:24.04
cua sb launch macos
cua sb launch windows:11
cua sb launch android:14

# Local (Docker / Lume / QEMU) — no API key needed
cua sb launch ubuntu:24.04 --local
cua sb launch macos --local

# Specify resources (cloud only)
cua sb launch ubuntu:24.04 --cpu 4 --memory 8GB --disk 50GB
cua sb launch ubuntu:24.04 --region europe

# Give it a name and get JSON output (useful in scripts)
cua sb launch ubuntu:24.04 --local --name my-sandbox --json

Arguments:

Argument	Description
`image`	Image to run: `macos`, `ubuntu:24.04`, `windows:11`, `android:14`, or a registry ref like `ghcr.io/org/img:tag`

Options:

Option	Description
`--local`	Run locally (Docker/Lume/QEMU) instead of Cua Cloud
`--name`	Sandbox name (auto-generated if omitted)
`--vm`	Force VM kind for Linux images (default: container)
`--cpu N`	Number of vCPUs (cloud only)
`--memory SIZE`	Memory — e.g. `8GB`, `4096MB` (cloud only)
`--disk SIZE`	Disk size — e.g. `50GB` (cloud only)
`--region NAME`	Cloud region (cloud only)
`--json`	Output `{"name": "...", "status": "ready"}`

Image shorthands:

String	Resolves to
`macos`	`Image.macos("26")`
`macos:sequoia`	`Image.macos("sequoia")`
`ubuntu:24.04`	`Image.linux("ubuntu", "24.04")`
`linux`	`Image.linux("ubuntu", "24.04")`
`windows:11`	`Image.windows("11")`
`android:14`	`Image.android("14")`
`ghcr.io/org/img`	`Image.from_registry("ghcr.io/org/img")`

`cua sb ls`

List running sandboxes.

cua sb ls                  # cloud sandboxes (requires API key)
cua sb ls --local          # local sandboxes only
cua sb ls --all            # both cloud and local
cua sb ls --json           # JSON output

Aliases: cua sb list

`cua sb info <name>`

Get details for a sandbox.

cua sb info my-sandbox
cua sb info my-sandbox --local
cua sb info my-sandbox --json

Alias: cua sb get <name>

`cua sb delete <name>`

Delete a sandbox permanently.

cua sb delete my-sandbox
cua sb delete my-sandbox --local
cua sb delete my-sandbox --force    # skip confirmation

Irreversible. All data on the sandbox is permanently lost.

`cua sb vnc <name>`

Open the sandbox desktop in your browser.

cua sb vnc my-sandbox
cua sb vnc my-sandbox --local

`cua sb shell <name>`

Open an interactive shell session.

cua sb shell my-sandbox
cua sb shell my-sandbox --local

# Run a single command
cua sb shell my-sandbox ls -la /
cua sb shell my-sandbox --cols 120 --rows 40

`cua sb exec <name> <command>`

Execute a command non-interactively (useful for scripts).

cua sb exec my-sandbox echo hello
cua sb exec my-sandbox --json uname -a

`cua sb suspend <name>` / `cua sb resume <name>`

Suspend a sandbox (preserves memory state) and resume it.

cua sb suspend my-sandbox
cua sb resume my-sandbox

`cua sb restart <name>`

Restart a sandbox.

cua sb restart my-sandbox

Authentication Commands

cua auth login                            # browser-based OAuth
cua auth login --api-key sk_cua-...       # direct API key

`cua auth env`

Write CUA_API_KEY to a .env file in the current directory.

cua auth env

`cua auth logout`

cua auth logout

Environment Variables

Variable	Description
`CUA_API_KEY`	API key for cloud authentication

Was this page helpful?

Command Reference

On this page