mirror of
https://github.com/trycua/computer.git
synced 2026-01-06 05:20:02 -06:00
Merge pull request #591 from trycua/blog/cua-cli-blogpost
Add cua cli blogpost
This commit is contained in:
Francesco Bonacci
254
blog/introducing-cua-cli.md
Normal file
254
blog/introducing-cua-cli.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Introducing the Cua CLI: Manage Cloud Sandboxes from Your Terminal
|
||||
|
||||
If you've been using our Cloud Sandboxes, you've probably been managing them through the web dashboard - clicking through forms to create instances, copying credentials, manually starting and stopping sandboxes. It works, but it's not exactly built for power users like yourself.
|
||||
|
||||
Today we're launching the **Cua CLI**: a command-line interface that brings the full power of our Cloud Sandbox platform to your terminal. Create, manage, and connect to Linux, Windows, or macOS sandboxes in seconds—all from a single command.
|
||||
|
||||
|
||||
|
||||
## What You Can Do
|
||||
|
||||
The Cua CLI handles everything you need to work with Cloud Sandboxes:
|
||||
|
||||
**Authentication**
|
||||
- Browser-based OAuth login with automatic credential storage
|
||||
- Direct API key support for CI/CD pipelines
|
||||
- Export credentials to `.env` files for SDK integration
|
||||
|
||||
**Sandbox Management**
|
||||
- Create sandboxes with your choice of OS, size, and region
|
||||
- List all your sandboxes with status and connection details
|
||||
- Start, stop, restart, and delete sandboxes
|
||||
- Open remote desktop (VNC) connections directly in your browser
|
||||
|
||||
**Two Command Styles**
|
||||
The CLI supports both flat and grouped command structures—use whichever fits your workflow:
|
||||
|
||||
```bash
|
||||
# Grouped style (explicit & clear)
|
||||
cua sb ls
|
||||
cua sb create --os linux --size small --region north-america
|
||||
cua sb vnc my-sandbox
|
||||
|
||||
# Flat style (quick & concise)
|
||||
cua ls
|
||||
cua create --os linux --size small --region north-america
|
||||
cua vnc my-sandbox
|
||||
```
|
||||
|
||||
Both styles work identically. The CLI shows grouped commands in help by default, but all flat commands remain available for backwards compatibility.
|
||||
|
||||
## Installation
|
||||
|
||||
One command installs everything (includes Bun runtime + Cua CLI):
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
Or install via npm if you prefer:
|
||||
|
||||
```bash
|
||||
npm install -g @trycua/cli
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
Authenticate with your Cua account:
|
||||
|
||||
```bash
|
||||
# Interactive browser login (recommended)
|
||||
cua auth login
|
||||
|
||||
# Or provide your API key directly
|
||||
cua auth login --api-key sk-your-api-key-here
|
||||
```
|
||||
|
||||
Create a sandbox:
|
||||
|
||||
```bash
|
||||
cua sb create --os linux --size small --region north-america
|
||||
# Sandbox created and ready: my-sandbox-abc123
|
||||
# Password: secure-password-here
|
||||
# Host: my-sandbox-abc123.sandbox.cua.ai
|
||||
```
|
||||
|
||||
List your sandboxes:
|
||||
|
||||
```bash
|
||||
cua sb list
|
||||
# NAME STATUS HOST
|
||||
# my-sandbox-abc123 running my-sandbox-abc123.sandbox.cua.ai
|
||||
# test-windows-456 stopped test-windows-456.sandbox.cua.ai
|
||||
```
|
||||
|
||||
Open a remote desktop:
|
||||
|
||||
```bash
|
||||
cua sb vnc my-sandbox-abc123
|
||||
# Opens your browser to the VNC interface with password pre-filled
|
||||
```
|
||||
|
||||
## SDK Integration
|
||||
|
||||
Export your API key to a `.env` file for seamless SDK integration:
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
cua auth env
|
||||
# Wrote /path/to/my-project/.env
|
||||
```
|
||||
|
||||
Then use it with our Python or TypeScript SDKs:
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
|
||||
computer = Computer(
|
||||
os_type="linux",
|
||||
provider_type="cloud",
|
||||
name="my-sandbox-abc123",
|
||||
api_key="your-api-key" # Or load from .env
|
||||
)
|
||||
|
||||
await computer.run()
|
||||
```
|
||||
|
||||
## Sandbox Sizes & Regions
|
||||
|
||||
Create sandboxes in the size and region that fits your needs:
|
||||
|
||||
**Sizes:**
|
||||
- `small` - 2 cores, 8 GB RAM, 128 GB SSD
|
||||
- `medium` - 4 cores, 16 GB RAM, 128 GB SSD
|
||||
- `large` - 8 cores, 32 GB RAM, 256 GB SSD
|
||||
|
||||
**Regions:**
|
||||
- `north-america`
|
||||
- `europe`
|
||||
- `asia-pacific`
|
||||
- `south-america`
|
||||
|
||||
**OS Options:**
|
||||
- `linux` - Ubuntu with XFCE desktop
|
||||
- `windows` - Windows 11 with Edge and Python
|
||||
- `macos` - macOS (preview access)
|
||||
|
||||
## Example Workflows
|
||||
|
||||
**Quick Testing Environment**
|
||||
```bash
|
||||
# Spin up a sandbox, test something, tear it down
|
||||
cua sb create --os linux --size small --region north-america
|
||||
# ... do your testing ...
|
||||
cua sb delete my-sandbox-abc123
|
||||
```
|
||||
|
||||
**Persistent Development Sandbox**
|
||||
```bash
|
||||
# Create a sandbox for long-term use
|
||||
cua sb create --os linux --size medium --region north-america
|
||||
|
||||
# Stop it when not in use (data persists)
|
||||
cua sb stop my-sandbox-abc123
|
||||
|
||||
# Start it again when needed
|
||||
cua sb start my-sandbox-abc123
|
||||
```
|
||||
|
||||
**CI/CD Integration**
|
||||
|
||||
```bash
|
||||
# Provision sandboxes in your pipeline
|
||||
export CUA_API_KEY="sk-your-api-key"
|
||||
cua auth login --api-key "$CUA_API_KEY"
|
||||
cua sb create --os linux --size large --region north-america
|
||||
|
||||
# Run your tests with the Cua Computer SDK
|
||||
python run_tests.py
|
||||
|
||||
# Clean up
|
||||
cua sb delete my-test-sandbox
|
||||
```
|
||||
|
||||
## Command Aliases
|
||||
|
||||
We've added aliases for common commands to speed up your workflow:
|
||||
|
||||
```bash
|
||||
# List aliases
|
||||
cua list # or: cua ls, cua ps, cua sb list
|
||||
|
||||
# VNC aliases
|
||||
cua vnc # or: cua open, cua sb vnc
|
||||
```
|
||||
|
||||
## FAQs
|
||||
|
||||
<details>
|
||||
<summary><strong>Can I use this in scripts and CI/CD?</strong></summary>
|
||||
|
||||
Yes. All commands support non-interactive mode with `--api-key` flags, and the CLI exits with proper status codes for scripting. The flat command style (`cua list`, `cua create`) is particularly useful for quick scripts.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Where are my credentials stored?</strong></summary>
|
||||
|
||||
API keys are stored in `~/.config/cua/cli.sqlite` using a local SQLite database. They never leave your machine. Use `cua auth logout` to clear stored credentials.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>What happens to passwords in the output?</strong></summary>
|
||||
|
||||
Passwords are hidden by default in `cua list` for security. Use `cua list --show-passwords` to display them when needed.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Can I manage sandboxes created through the web dashboard?</strong></summary>
|
||||
|
||||
Yes. The CLI and dashboard share the same API. Any sandbox you create in the dashboard will show up in `cua list`, and vice versa.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>How do I update the CLI?</strong></summary>
|
||||
|
||||
If you installed via script:
|
||||
```bash
|
||||
curl -LsSf https://cua.ai/cli/install.sh | sh
|
||||
```
|
||||
|
||||
If you installed via npm:
|
||||
```bash
|
||||
npm install -g @trycua/cli@latest
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## What's Next
|
||||
|
||||
We're actively iterating based on feedback. Planned features include:
|
||||
- SSH key management for secure sandbox access
|
||||
- Template-based sandbox creation
|
||||
- Batch operations (start/stop multiple sandboxes)
|
||||
- Custom sandbox configurations
|
||||
- Snapshot management
|
||||
|
||||
If there's a feature you need, let us know in [Discord](https://discord.gg/cua-ai).
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **Documentation**: [https://cua.ai/docs/libraries/cua-cli/commands](https://cua.ai/docs/libraries/cua-cli/commands)
|
||||
- **Installation Guide**: [https://cua.ai/docs/libraries/cua-cli/installation](https://cua.ai/docs/libraries/cua-cli/installation)
|
||||
- **Discord Community**: [https://discord.gg/cua-ai](https://discord.gg/cua-ai)
|
||||
|
||||
---
|
||||
|
||||
Get started at [cua.ai](https://cua.ai) or check out the [quickstart guide](https://cua.ai/docs/get-started/quickstart).
|
||||
@@ -445,7 +445,7 @@ Your sandbox will be created and you'll see output like:
|
||||
```
|
||||
Sandbox created and ready: my-sandbox-abc123
|
||||
Password: secure-password-here
|
||||
Host: my-sandbox-abc123.containers.cloud.trycua.com
|
||||
Host: my-sandbox-abc123.sandbox.cua.ai
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
@@ -123,15 +123,15 @@ cua ps
|
||||
**Example Output (default, passwords hidden):**
|
||||
```
|
||||
NAME STATUS HOST
|
||||
my-dev-sandbox running my-dev-sandbox.containers.cloud.trycua.com
|
||||
test-windows stopped test-windows.containers.cloud.trycua.com
|
||||
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.containers.cloud.trycua.com
|
||||
test-windows stopped another-pass-456 test-windows.containers.cloud.trycua.com
|
||||
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`
|
||||
@@ -165,7 +165,7 @@ cua create --os macos --size large --region asia-pacific
|
||||
```bash
|
||||
Sandbox created and ready: my-new-sandbox-abc123
|
||||
Password: secure-password-here
|
||||
Host: my-new-sandbox-abc123.containers.cloud.trycua.com
|
||||
Host: my-new-sandbox-abc123.sandbox.cua.ai
|
||||
```
|
||||
|
||||
**Provisioning (Status 202):**
|
||||
@@ -249,7 +249,7 @@ cua open <name>
|
||||
**Example:**
|
||||
```bash
|
||||
$ cua vnc my-dev-sandbox
|
||||
Opening NoVNC: https://my-dev-sandbox.containers.cloud.trycua.com/vnc.html?autoconnect=true&password=...
|
||||
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.
|
||||
|
||||
@@ -213,7 +213,7 @@ const openHandler = async (argv: Record<string, unknown>) => {
|
||||
const host =
|
||||
sandbox.host && sandbox.host.length
|
||||
? sandbox.host
|
||||
: `${sandbox.name}.containers.cloud.trycua.com`;
|
||||
: `${sandbox.name}.sandbox.cua.ai`;
|
||||
const url = `https://${host}/vnc.html?autoconnect=true&password=${encodeURIComponent(sandbox.password)}`;
|
||||
console.log(`Opening NoVNC: ${url}`);
|
||||
await openInBrowser(url);
|
||||
|
||||
Reference in New Issue
Block a user