Commands

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 start, cua stop, cua restart, cua delete, cua vnc

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 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.

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?

On this page