Metadata-Version: 2.4
Name: cua-cli
Version: 0.1.14
Summary: Unified CLI for CUA - Computer-Use Agents
Project-URL: Homepage, https://github.com/trycua/cua
Project-URL: Documentation, https://docs.trycua.com
Project-URL: Repository, https://github.com/trycua/cua
Project-URL: Issues, https://github.com/trycua/cua/issues
Author-email: TryCua <hello@trycua.com>
License-Expression: MIT
Keywords: agents,cli,cloud,computer-use,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.12
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: cua-auto[all]>=0.1.0
Requires-Dist: cua-computer>=0.5.0
Requires-Dist: cua-core<0.4.0,>=0.3.0
Requires-Dist: cua-sandbox<0.2.0,>=0.1.28
Requires-Dist: keyring>=25.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: fastmcp>=2.0; extra == 'all'
Requires-Dist: litellm==1.86.2; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == 'mcp'
Provides-Extra: skills
Requires-Dist: litellm==1.86.2; extra == 'skills'
Description-Content-Type: text/markdown

# CUA CLI

Unified command-line interface for CUA (Computer-Use Agents).

## Installation

```bash
pip install --extra-index-url https://wheels.cua.ai/simple cua-cli
```

## Usage

```bash
# Authentication
cua auth login              # Authenticate with run.cua.ai device authorization
cua auth login --no-browser # Print the verification URL without opening a browser
cua auth status             # Show local session status
cua auth logout             # Revoke the refresh token and remove local credentials

# Sandbox Management
cua sb list                 # List all sandboxes
cua sb create --os linux --size medium --region north-america
cua sb get <name>           # Get sandbox details
cua sb start <name>         # Start a stopped sandbox
cua sb stop <name>          # Stop a running sandbox
cua sb restart <name>       # Restart a sandbox
cua sb suspend <name>       # Suspend a sandbox
cua sb delete <name>        # Delete a sandbox
cua sb vnc <name>           # Open sandbox in browser

# Image Management
cua image list              # List cloud images
cua image list --local      # List local images
cua image push <name>       # Upload image to cloud
cua image pull <name>       # Download image from cloud
cua image delete <name>     # Delete cloud image

# Skills Management
cua skills list             # List recorded skills
cua skills read <name>      # Read a skill's content
cua skills record <name>    # Record a new skill
cua skills replay <name>    # Replay a skill
cua skills delete <name>    # Delete a skill
cua skills clean            # Delete all skills

# MCP Server (for AI assistants)
cua serve-mcp               # Start MCP server with all permissions
cua serve-mcp --permissions sandbox:all,computer:readonly
```

## Installation Options

```bash
# Basic installation
pip install --extra-index-url https://wheels.cua.ai/simple cua-cli

# With MCP server support
pip install --extra-index-url https://wheels.cua.ai/simple "cua-cli[mcp]"

# With skills recording (VLM captioning)
pip install --extra-index-url https://wheels.cua.ai/simple "cua-cli[skills]"

# Full installation
pip install --extra-index-url https://wheels.cua.ai/simple "cua-cli[all]"
```

## MCP Integration

To use CUA with Claude Code or other MCP-compatible AI assistants:

```bash
# Add CUA as an MCP server
claude mcp add cua -- cua serve-mcp

# With specific permissions
claude mcp add cua -- cua serve-mcp --permissions sandbox:all,computer:readonly

# With a default sandbox
claude mcp add cua -- cua serve-mcp --sandbox my-sandbox
```

### Available Permissions

- `all` - All permissions
- `sandbox:all` - Full sandbox management
- `sandbox:readonly` - List and get sandboxes only
- `computer:all` - Full computer control
- `computer:readonly` - Screenshots only
- `skills:all` - Full skills management
- `skills:readonly` - List and read skills only

Individual permissions: `sandbox:list`, `sandbox:create`, `sandbox:delete`, `sandbox:start`, `sandbox:stop`, `sandbox:restart`, `sandbox:suspend`, `sandbox:get`, `sandbox:vnc`, `computer:screenshot`, `computer:click`, `computer:type`, `computer:key`, `computer:scroll`, `computer:drag`, `computer:hotkey`, `computer:clipboard`, `computer:file`, `computer:shell`, `computer:window`, `skills:list`, `skills:read`, `skills:record`, `skills:delete`

## Environment Variables

- Authentication uses OIDC device authorization discovered from `https://auth.cua.ai/realms/cyclops-cs`, while authenticated cloud requests use `https://run.cua.ai`. Tokens are stored in the operating system credential vault; the CLI does not read API keys from environment variables or write them to `.env` files.
- `CUA_MCP_PERMISSIONS`: Default MCP permissions (comma-separated)
- `CUA_SANDBOX`: Default sandbox name for computer commands

## Cloud Authentication

`cua auth login` uses the standard OAuth device authorization flow. It discovers Keycloak endpoints from `https://auth.cua.ai/realms/cyclops-cs`, while the short verification UI is served from `https://run.cua.ai/device`. The CLI prints a verification URL and code, so it also works over SSH or in CI-style terminals; use `--no-browser` to prevent an automatic browser attempt. Complete the verification in any browser, then return to the terminal while the CLI polls for approval.

Access tokens refresh automatically before authenticated `run.cua.ai` requests. `cua auth logout` asks the issuer to revoke the refresh token and always removes the local credential-vault entry, even when the network is unavailable. The CLI never prints access or refresh tokens.

## GitHub Actions workload identity

Use `cua wif-token github` from a GitHub Actions job to obtain a GitHub OIDC token for Fleets. The command runs only in GitHub Actions, requests the `fleets` audience, and prints only the raw token. It does not use the interactive `cua auth login` session.

`FLEETS_TOKEN` is ephemeral and process-scoped. When it is set, it takes precedence over the interactive session for Fleet operations.

```yaml
permissions:
  id-token: write
  contents: read

steps:
  - name: Run a non-interactive Fleets sandbox
    run: |
      export FLEETS_TOKEN="$(cua wif-token github)"
      cua sb launch ghcr.io/trycua/mini-swe:latest --name sandbox
      cua sb exec sandbox -- pwd
      cua sb delete sandbox --force
```

Use the exact GitHub-authorized sandbox name `sandbox` and the Mini SWE image `ghcr.io/trycua/mini-swe:latest`. `cua sb delete sandbox --force` releases the claim while preserving the reconciled one-replica pool, template, and namespace for the next claim.
