Using the Cloud CLI

The Cua Cloud CLI lets you create, manage, and connect to cloud sandboxes directly from your terminal. This is the fastest way to get a sandbox running without writing any code.

Installation

Install the CLI globally using npm or bun:

npm install -g @trycua/cli

bun install -g @trycua/cli

Verify the installation:

cua --version

Authentication

Before managing sandboxes, authenticate with your Cua account:

# Browser-based login (opens OAuth flow)
cua auth login

# Or use an API key directly
cua auth login --api-key sk_cua-api01_...

To write your API key to a .env file for use in projects:

cua auth env

This creates or updates .env with your CUA_API_KEY.

Creating a Sandbox

Create a new cloud sandbox with the create command:

cua sandbox create --os linux --size small --region north-america

Required options:

Compute tiers:

The command returns once your sandbox is ready. You'll see the sandbox name, which you'll use for all other commands.

Listing Sandboxes

View all your sandboxes:

cua sandbox list

Output shows NAME, STATUS, and HOST for each sandbox. Status values:

• running - Ready to use
• stopped - Not running (no charges)
• pending - Starting up
• suspended - Memory state preserved
• terminated - Deleted

Shorthand aliases: cua ls, cua ps, cua sb list

Managing Sandbox Lifecycle

Start, stop, and restart sandboxes:

# Start a stopped sandbox (hot-start in under 1 second)
cua sandbox start my-sandbox

# Stop a running sandbox (preserves data)
cua sandbox stop my-sandbox

# Restart a sandbox
cua sandbox restart my-sandbox

# Suspend (preserves memory state)
cua sandbox suspend my-sandbox

# Permanently delete
cua sandbox delete my-sandbox

Stopping a sandbox preserves all files, installed software, and browser profiles. You only pay for compute time while the sandbox is running.

Connecting to a Sandbox

Open the sandbox desktop in your browser:

cua sandbox vnc my-sandbox

This opens a NoVNC session with the password pre-filled. You can interact with the desktop directly in your browser.

Shorthand: cua open my-sandbox

Getting Sandbox Details

View detailed information about a sandbox:

cua sandbox get my-sandbox

Add flags for more details:

# Include password in output
cua sandbox get my-sandbox --show-passwords

# Include VNC URL
cua sandbox get my-sandbox --show-vnc-url

# JSON output for scripting
cua sandbox get my-sandbox --json

Command Reference

The CLI supports both grouped and flat command styles:

Example Workflow

Here's a typical workflow for setting up and using a sandbox:

# 1. Login
cua auth login

# 2. Create a Linux sandbox
cua sandbox create --os linux --size small --region north-america
# Output: Created sandbox "curious-fox-123"

# 3. Open the desktop in your browser
cua open curious-fox-123

# 4. Export your API key for SDK usage
cua auth env

# 5. Use the sandbox with Python SDK
python my_agent.py

# 6. Stop when done (preserves data, stops charges)
cua stop curious-fox-123

Next Step

Once your sandbox is running, proceed to Using the Computer SDK to connect programmatically, or Using the Agent SDK to add AI automation.