Command Reference

Overview

The Cua CLI provides commands for authentication and sandbox management.

Command Styles

The CLI supports two command styles for flexibility:

Flat style (quick & concise):

cua list
cua create --os linux --size small --region north-america
cua start my-sandbox

Grouped style (explicit & clear):

cua sb list         # or: cua sandbox list
cua sb create       # or: cua sandbox create
cua sb start        # or: cua sandbox start

Both styles work identically - use whichever you prefer!

Available Commands

Authentication - cua auth login, cua auth env, cua auth logout (also available as flat commands: cua login, cua env, cua logout)
Sandbox Management - cua list, cua create, cua get, cua start, cua stop, cua restart, cua delete, cua vnc, cua shell, cua exec

Authentication Commands

Authenticate with your Cua account using browser-based OAuth flow.

# Interactive browser login
cua auth login

# Direct API key login
cua auth login --api-key sk-your-api-key-here

# Alternative flat style
cua login
cua login --api-key sk-your-api-key-here

Options:

--api-key <key> - Provide API key directly instead of browser flow

Example:

$ cua auth login
Opening browser for CLI auth...
API key saved

`cua auth env`

Create or update a .env file in the current directory with your Cua API key.

cua auth env

# Alternative flat style
cua env

Example:

$ cua auth env
Wrote /path/to/your/project/.env

The generated .env file will contain:

CUA_API_KEY=sk-your-api-key-here

`cua auth logout`

Remove the stored API key from your system.

cua auth logout

# Alternative flat style
cua logout

Example:

$ cua auth logout
Logged out

Sandbox Commands

`cua list`

List all your sandboxes with their current status. Passwords are hidden by default for security.

# List sandboxes (passwords hidden)
cua list

# Show passwords explicitly
cua list --show-passwords

# Alternative aliases
cua ls
cua ps

Example Output (default, passwords hidden):

NAME              STATUS    HOST
my-dev-sandbox    running   my-dev-sandbox.sandbox.cua.ai
test-windows      stopped   test-windows.sandbox.cua.ai

Example Output (with --show-passwords):

NAME              STATUS    PASSWORD           HOST
my-dev-sandbox    running   secure-pass-123    my-dev-sandbox.sandbox.cua.ai
test-windows      stopped   another-pass-456   test-windows.sandbox.cua.ai

`cua create`

Create a new sandbox.

cua create --os <OS> --size <SIZE> --region <REGION>

Required Options:

--os - Operating system: linux, windows, macos
--size - Sandbox size: small, medium, large
--region - Region: north-america, europe, asia-pacific, south-america

Examples:

# Create a small Linux sandbox in North America
cua create --os linux --size small --region north-america

# Create a medium Windows sandbox in Europe
cua create --os windows --size medium --region europe

# Create a large macOS sandbox in Asia Pacific
cua create --os macos --size large --region asia-pacific

Response Types:

Immediate (Status 200):

Sandbox created and ready: my-new-sandbox-abc123
Password: secure-password-here
Host: my-new-sandbox-abc123.sandbox.cua.ai

Provisioning (Status 202):

Sandbox provisioning started: my-new-sandbox-abc123
Job ID: job-xyz789
Use 'cua list' to monitor provisioning progress

`cua get`

Get detailed information about a specific sandbox, including computer-server health status.

cua get <name>

# With additional options
cua get <name> --json
cua get <name> --show-passwords
cua get <name> --show-vnc-url

Options:

--json - Output all details in JSON format
--show-passwords - Include password in output
--show-vnc-url - Include computed NoVNC URL

Example Output (default):

$ cua get my-dev-sandbox
Name: my-dev-sandbox
Status: running
Host: my-dev-sandbox.containers.cloud.trycua.com
OS Type: linux
Computer Server Version: 0.1.30
Computer Server Status: healthy

Example Output (with --show-passwords and --show-vnc-url):

$ cua get my-dev-sandbox --show-passwords --show-vnc-url
Name: my-dev-sandbox
Status: running
Host: my-dev-sandbox.containers.cloud.trycua.com
Password: secure-pass-123
OS Type: linux
Computer Server Version: 0.1.30
Computer Server Status: healthy
VNC URL: https://my-dev-sandbox.containers.cloud.trycua.com/vnc.html?autoconnect=true&password=secure-pass-123

Example Output (JSON format):

$ cua get my-dev-sandbox --json
{
  "name": "my-dev-sandbox",
  "status": "running",
  "host": "my-dev-sandbox.containers.cloud.trycua.com",
  "os_type": "linux",
  "computer_server_version": "0.1.30",
  "computer_server_status": "healthy"
}

Computer Server Health Check:

The cua get command automatically probes the computer-server when the sandbox is running:

Checks OS type via https://{host}:8443/status
Checks version via https://{host}:8443/cmd
Shows "Computer Server Status: healthy" when both probes succeed
Uses a 3-second timeout for each probe

The computer server status is only checked for running sandboxes. Stopped or suspended sandboxes will not show computer server information.

`cua start`

Start a stopped sandbox.

cua start <name>

Example:

$ cua start my-dev-sandbox
Start accepted

`cua stop`

Stop a running sandbox.

cua stop <name>

Example:

$ cua stop my-dev-sandbox
stopping

`cua restart`

Restart a sandbox.

cua restart <name>

Example:

$ cua restart my-dev-sandbox
restarting

`cua delete`

Delete a sandbox permanently.

cua delete <name>

Example:

$ cua delete old-test-sandbox
Sandbox deletion initiated: deleting

This action is irreversible. All data on the sandbox will be permanently lost.

`cua vnc`

Open the VNC interface for a sandbox in your browser.

cua vnc <name>

# Alternative alias
cua open <name>

Example:

$ cua vnc my-dev-sandbox
Opening NoVNC: https://my-dev-sandbox.sandbox.cua.ai/vnc.html?autoconnect=true&password=...

This command automatically opens your default browser to the VNC interface with the correct password pre-filled.

`cua shell`

Open an interactive shell session in a running sandbox.

cua shell <name>

# Run a command through the shell
cua shell <name> <command...>

# Specify terminal size
cua shell --cols 120 --rows 40 <name>

Options:

--cols <number> - Terminal width in columns (default: current terminal width or 80)
--rows <number> - Terminal height in rows (default: current terminal height or 24)

Examples:

# Open interactive bash shell
$ cua shell my-dev-sandbox
root@sandbox:~# ls
Desktop  Documents  Downloads
root@sandbox:~# exit
exit

# Run a single command through the shell
$ cua shell my-dev-sandbox echo "Hello from sandbox"
Hello from sandbox

# Check system info
$ cua shell my-dev-sandbox uname -a
Linux sandbox 5.15.0 #1 SMP x86_64 GNU/Linux

The shell command connects via WebSocket to the sandbox's PTY endpoint, providing a full interactive terminal experience with proper TTY handling.

`cua exec`

Execute a command directly in a sandbox without an interactive shell.

cua exec <name> <command...>

# Get JSON output
cua exec --json <name> <command...>

Options:

--json - Output result as JSON including stdout, stderr, and exit code

Examples:

# Run a command
$ cua exec my-dev-sandbox ls -la /tmp
total 8
drwxrwxrwt 2 root root 4096 Mar 13 10:00 .
drwxr-xr-x 1 root root 4096 Mar 13 09:00 ..

# Get JSON output with exit code
$ cua exec --json my-dev-sandbox echo "test"
{
  "stdout": "test\n",
  "stderr": "",
  "return_code": 0
}

# Check exit codes for scripting
$ cua exec my-dev-sandbox test -f /etc/passwd && echo "File exists"
File exists

Exit Codes:

The exec command returns the exit code from the executed command, making it suitable for scripting:

# Returns 0 on success
cua exec my-sandbox true
echo $?  # 0

# Returns non-zero on failure
cua exec my-sandbox false
echo $?  # 1

Unlike cua shell, the exec command runs commands non-interactively without PTY allocation. Use shell for interactive sessions and exec for automation scripts.

Global Options

Help

Get help for any command:

cua --help
cua auth login --help
cua create --help
cua list --help

Error Handling

The CLI provides clear error messages for common issues:

Authentication Errors

$ cua list
Unauthorized. Try 'cua auth login' again.

Sandbox Not Found

$ cua start nonexistent-sandbox
Sandbox not found

Invalid Configuration

$ cua create --os invalid --configuration small --region north-america
Invalid request or unsupported configuration

Tips and Best Practices

1. Use Descriptive Sandbox Names

# Good
cua create --os linux --size small --region north-america
# Then rename or use meaningful names in the dashboard

# Better workflow
cua list  # Check the generated name
# Use that name consistently

2. Environment Management

# Set up your project with API key
cd my-project
cua auth env
# Now your project has CUA_API_KEY in .env

3. Quick Sandbox Access

# Create aliases for frequently used sandboxes
alias dev-sandbox="cua vnc my-development-sandbox"
alias prod-sandbox="cua vnc my-production-sandbox"

4. Monitoring Provisioning

# For sandboxes that need provisioning time
cua create --os windows --size large --region europe
# Sandbox provisioning started: my-sandbox-abc123
# Job ID: job-xyz789

# Check status periodically
watch -n 5 cua list

Next Steps

Was this page helpful?

Command Reference

On this page