From fec44584f557618d6b9a4cc044e9c75026ec8c0b Mon Sep 17 00:00:00 2001 From: Dillon DuPont Date: Wed, 12 Nov 2025 12:25:02 -0500 Subject: [PATCH] add cua-cli page --- .../docs/libraries/cua-cli/commands.mdx | 320 ++++++++++++++++++ docs/content/docs/libraries/cua-cli/index.mdx | 58 ++++ .../docs/libraries/cua-cli/installation.mdx | 152 +++++++++ docs/content/docs/libraries/cua-cli/meta.json | 9 + 4 files changed, 539 insertions(+) create mode 100644 docs/content/docs/libraries/cua-cli/commands.mdx create mode 100644 docs/content/docs/libraries/cua-cli/index.mdx create mode 100644 docs/content/docs/libraries/cua-cli/installation.mdx create mode 100644 docs/content/docs/libraries/cua-cli/meta.json diff --git a/docs/content/docs/libraries/cua-cli/commands.mdx b/docs/content/docs/libraries/cua-cli/commands.mdx new file mode 100644 index 00000000..c60d5a12 --- /dev/null +++ b/docs/content/docs/libraries/cua-cli/commands.mdx @@ -0,0 +1,320 @@ +--- +title: Commands +description: Complete reference for all CUA CLI commands +--- + +import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; +import { Callout } from 'fumadocs-ui/components/callout'; + +## Overview + +The CUA CLI provides two main command groups: + +- **`cua auth`** - Authentication and API key management +- **`cua vm`** - Virtual machine lifecycle management + +## Authentication Commands + +### `cua auth login` + +Authenticate with your CUA account using browser-based OAuth flow. + +```bash +# Interactive browser login +cua auth login + +# Direct API key login +cua auth login --api-key sk-your-api-key-here +``` + +**Options:** +- `--api-key ` - Provide API key directly instead of browser flow + +**Example:** +```bash +$ cua auth login +Opening browser for CLI auth... +API key saved +``` + +### `cua auth pull` + +Create or update a `.env` file in the current directory with your CUA API key. + +```bash +cua auth pull +``` + +**Example:** +```bash +$ cua auth pull +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. + +```bash +cua auth logout +``` + +**Example:** +```bash +$ cua auth logout +Logged out +``` + +## Virtual Machine Commands + +### `cua vm list` + +List all your virtual machines with their current status. + +```bash +cua vm list +``` + +**Example Output:** +``` +┌─────────────────┬──────────┬────────┬─────────────────┬──────────────────────────────────────┐ +│ Name │ Status │ OS │ Configuration │ Host │ +├─────────────────┼──────────┼────────┼─────────────────┼──────────────────────────────────────┤ +│ my-dev-vm │ running │ linux │ small │ my-dev-vm.containers.cloud.trycua.com │ +│ test-windows │ stopped │ windows│ medium │ test-windows.containers.cloud.trycua.com │ +└─────────────────┴──────────┴────────┴─────────────────┴──────────────────────────────────────┘ +``` + +### `cua vm create` + +Create a new virtual machine. + +```bash +cua vm create --os --configuration --region +``` + +**Required Options:** +- `--os` - Operating system: `linux`, `windows`, `macos` +- `--configuration` - VM size: `small`, `medium`, `large` +- `--region` - Region: `north-america`, `europe`, `asia-pacific`, `south-america` + +**Examples:** +```bash +# Create a small Linux VM in North America +cua vm create --os linux --configuration small --region north-america + +# Create a medium Windows VM in Europe +cua vm create --os windows --configuration medium --region europe + +# Create a large macOS VM in Asia Pacific +cua vm create --os macos --configuration large --region asia-pacific +``` + +**Response Types:** + +**Immediate (Status 200):** +```bash +VM created and ready: my-new-vm-abc123 +Password: secure-password-here +Host: my-new-vm-abc123.containers.cloud.trycua.com +``` + +**Provisioning (Status 202):** +```bash +VM provisioning started: my-new-vm-abc123 +Job ID: job-xyz789 +Use 'cua vm list' to monitor provisioning progress +``` + +### `cua vm start` + +Start a stopped virtual machine. + +```bash +cua vm start +``` + +**Example:** +```bash +$ cua vm start my-dev-vm +Start accepted +``` + +### `cua vm stop` + +Stop a running virtual machine. + +```bash +cua vm stop +``` + +**Example:** +```bash +$ cua vm stop my-dev-vm +stopping +``` + +### `cua vm restart` + +Restart a virtual machine. + +```bash +cua vm restart +``` + +**Example:** +```bash +$ cua vm restart my-dev-vm +restarting +``` + +### `cua vm delete` + +Delete a virtual machine permanently. + +```bash +cua vm delete +``` + +**Example:** +```bash +$ cua vm delete old-test-vm +VM deletion initiated: deleting +``` + + + This action is irreversible. All data on the VM will be permanently lost. + + +### `cua vm vnc` + +Open the VNC interface for a VM in your browser. + +```bash +cua vm vnc +``` + +**Example:** +```bash +$ cua vm vnc my-dev-vm +Opening NoVNC: https://my-dev-vm.containers.cloud.trycua.com/vnc.html?autoconnect=true&password=... +``` + +This command automatically opens your default browser to the VNC interface with the correct password pre-filled. + +### `cua vm chat` + +Open the CUA Dashboard Playground for a VM in your browser. + +```bash +cua vm chat +``` + +**Example:** +```bash +$ cua vm chat my-dev-vm +Opening Playground: https://cua.ai/dashboard/playground?host=... +``` + +This opens the full CUA playground interface where you can interact with your VM using AI agents. + +## Global Options + +### Help + +Get help for any command: + +```bash +cua --help +cua auth --help +cua vm --help +cua vm create --help +``` + +### Environment Variables + +You can override default endpoints using environment variables: + +```bash +# Use staging environment +export CUA_API_BASE=https://api.staging.cua.ai +export CUA_WEBSITE_URL=https://staging.cua.ai + +cua vm list # Uses staging API +``` + +**Available Variables:** +- `CUA_API_BASE` - API endpoint (default: `https://api.cua.ai`) +- `CUA_WEBSITE_URL` - Website URL (default: `https://cua.ai`) + +## Error Handling + +The CLI provides clear error messages for common issues: + +### Authentication Errors +```bash +$ cua vm list +Unauthorized. Try 'cua auth login' again. +``` + +### VM Not Found +```bash +$ cua vm start nonexistent-vm +VM not found +``` + +### Invalid Configuration +```bash +$ cua vm create --os invalid --configuration small --region north-america +Invalid request or unsupported configuration +``` + +## Tips and Best Practices + +### 1. Use Descriptive VM Names +```bash +# Good +cua vm create --os linux --configuration small --region north-america +# Then rename or use meaningful names in the dashboard + +# Better workflow +cua vm list # Check the generated name +# Use that name consistently +``` + +### 2. Environment Management +```bash +# Set up your project with API key +cd my-project +cua auth pull +# Now your project has CUA_API_KEY in .env +``` + +### 3. Quick VM Access +```bash +# Create aliases for frequently used VMs +alias dev-vm="cua vm chat my-development-vm" +alias prod-vm="cua vm vnc my-production-vm" +``` + +### 4. Monitoring Provisioning +```bash +# For VMs that need provisioning time +cua vm create --os windows --configuration large --region europe +# VM provisioning started: my-vm-abc123 +# Job ID: job-xyz789 + +# Check status periodically +watch -n 5 cua vm list +``` + +## Next Steps + +- [Get started with the quickstart guide](/get-started/quickstart#cli-quickstart) +- [Learn about CUA computers](/computer-sdk/computers) +- [Explore agent automation](/agent-sdk/agent-loops) diff --git a/docs/content/docs/libraries/cua-cli/index.mdx b/docs/content/docs/libraries/cua-cli/index.mdx new file mode 100644 index 00000000..3fe90c0f --- /dev/null +++ b/docs/content/docs/libraries/cua-cli/index.mdx @@ -0,0 +1,58 @@ +--- +title: Cua CLI +description: Command-line interface for managing Cua cloud VMs and authentication +--- + +import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; + +The Cua CLI is a command-line tool that provides an intuitive interface for managing your Cua cloud virtual machines and authentication. It offers a streamlined workflow for creating, managing, and connecting to cloud sandboxes. + +## Key Features + +- **Authentication Management**: Secure login with browser-based OAuth flow +- **VM Lifecycle**: Create, start, stop, restart, and delete cloud VMs +- **Quick Access**: Direct links to VNC and playground interfaces +- **Cross-Platform**: Works on macOS, Linux, and Windows +- **Environment Integration**: Automatic `.env` file generation + +## Quick Example + +```bash +# Install the CLI (installs Bun + CUA CLI) +curl -LsSf https://cua.ai/cli/install.sh | sh + +# Login to your CUA account +cua auth login + +# Create a new Linux VM +cua vm create --os linux --configuration small --region north-america + +# List your VMs +cua vm list + +# Open the playground for your VM +cua vm chat my-vm-name +``` + +## Use Cases + +### Development Workflow +- Quickly spin up cloud sandboxes for testing +- Manage multiple VMs across different regions +- Integrate with CI/CD pipelines + +### Team Collaboration +- Share VM configurations and access +- Standardize development environments +- Quick onboarding for new team members + +### Automation +- Script VM provisioning and management +- Integrate with deployment workflows +- Automate environment setup + +## Next Steps + +- [Install the CLI](/libraries/cua-cli/installation) +- [Learn about available commands](/libraries/cua-cli/commands) +- [Get started with the quickstart guide](/get-started/quickstart#cli-quickstart) diff --git a/docs/content/docs/libraries/cua-cli/installation.mdx b/docs/content/docs/libraries/cua-cli/installation.mdx new file mode 100644 index 00000000..5a2fd49b --- /dev/null +++ b/docs/content/docs/libraries/cua-cli/installation.mdx @@ -0,0 +1,152 @@ +--- +title: Installation +description: Install the CUA CLI on your system +--- + +import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; +import { Callout } from 'fumadocs-ui/components/callout'; + +## Quick Install + +The fastest way to install the CUA CLI is using our installation scripts: + + + + ```bash + curl -LsSf https://cua.ai/cli/install.sh | sh + ``` + + + ```powershell + powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex" + ``` + + + +These scripts will automatically: +1. Install [Bun](https://bun.sh) (a fast JavaScript runtime) +2. Install the CUA CLI via `bun add -g @trycua/cli` + + + The installation scripts will automatically detect your system and install the appropriate binary to your PATH. + + +## Alternative: npm Install + +You can also install the CLI via npm if you prefer: + +```bash +npm install -g @trycua/cli +``` + + + The npm package requires Node.js 18+ to be installed on your system. + + +## Verify Installation + +After installation, verify the CLI is working: + +```bash +cua --help +``` + +You should see the CLI help output with available commands. + +## First Time Setup + +After installation, you'll need to authenticate with your CUA account: + +```bash +# Login with browser-based OAuth flow +cua auth login + +# Or provide your API key directly +cua auth login --api-key sk-your-api-key-here +``` + +## Updating + +To update to the latest version: + + + + Re-run the installation script: + ```bash + # macOS/Linux + curl -LsSf https://cua.ai/cli/install.sh | sh + + # Windows + powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex" + ``` + + + ```bash + npm update -g @trycua/cli + ``` + + + +## Uninstalling + + + + Remove the binary from your PATH: + ```bash + # macOS/Linux + rm $(which cua) + + # Windows + # Remove from your PATH or delete the executable + ``` + + + ```bash + npm uninstall -g @trycua/cli + ``` + + + +## Troubleshooting + +### Command Not Found + +If you get a "command not found" error after installation: + +1. **Check your PATH**: Make sure the installation directory is in your PATH +2. **Restart your terminal**: Close and reopen your terminal/command prompt +3. **Manual PATH setup**: Add the installation directory to your PATH manually + +### Permission Issues + +If you encounter permission issues during installation: + + + + Try running with sudo (not recommended for the curl method): + ```bash + # If using npm + sudo npm install -g @trycua/cli + ``` + + + Run PowerShell as Administrator: + ```powershell + # Right-click PowerShell and "Run as Administrator" + powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex" + ``` + + + +### Network Issues + +If the installation script fails due to network issues: + +1. **Check your internet connection** +2. **Try the npm installation method instead** +3. **Check if your firewall is blocking the download** + +## Next Steps + +- [Learn about CLI commands](/libraries/cua-cli/commands) +- [Follow the quickstart guide](/get-started/quickstart#cli-quickstart) diff --git a/docs/content/docs/libraries/cua-cli/meta.json b/docs/content/docs/libraries/cua-cli/meta.json new file mode 100644 index 00000000..8c40c41d --- /dev/null +++ b/docs/content/docs/libraries/cua-cli/meta.json @@ -0,0 +1,9 @@ +{ + "title": "CLI", + "description": "Command-line interface for CUA", + "pages": [ + "index", + "installation", + "commands" + ] +} \ No newline at end of file