Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Fix broken docs formatting for CLI, add CLI completions (#790)

ddupontf6b18d9b8bdd
diff --git a/.github/workflows/docker-reusable-build.yml b/.github/workflows/docker-reusable-build.yml
index 09d395d1be..bcba80284c 100644
--- a/.github/workflows/docker-reusable-build.yml
+++ b/.github/workflows/docker-reusable-build.yml
@@ -1,7 +1,7 @@
name: Reusable Docker Build Workflow
on:
- workflow_dispatch: # Prevents phantom runs on push, allows manual testing
+ workflow_dispatch: # Prevents phantom runs on push, allows manual testing
workflow_call:
inputs:
image_name:
diff --git a/.github/workflows/docker-reusable-publish.yml b/.github/workflows/docker-reusable-publish.yml
index 4aa50f7c4a..3e51545e74 100644
--- a/.github/workflows/docker-reusable-publish.yml
+++ b/.github/workflows/docker-reusable-publish.yml
@@ -1,7 +1,7 @@
name: Reusable Docker Publish Workflow
on:
- workflow_dispatch: # Prevents phantom runs on push, allows manual testing
+ workflow_dispatch: # Prevents phantom runs on push, allows manual testing
workflow_call:
inputs:
image_name:
diff --git a/docs/content/docs/cua/guide/get-started/using-cloud-cli.mdx b/docs/content/docs/cua/guide/get-started/using-cloud-cli.mdx
index a332494fdf..c192fcb2f5 100644
--- a/docs/content/docs/cua/guide/get-started/using-cloud-cli.mdx
+++ b/docs/content/docs/cua/guide/get-started/using-cloud-cli.mdx
@@ -13,8 +13,16 @@ The Cua Cloud CLI lets you create, manage, and connect to cloud sandboxes direct
Install the CLI globally using npm or bun:
<Tabs items={['npm', 'bun']}>
- <Tab value="npm">```bash npm install -g @trycua/cli ```</Tab>
- <Tab value="bun">```bash bun install -g @trycua/cli ```</Tab>
+ <Tab value="npm">
+ ```bash
+ npm install -g @trycua/cli
+ ```
+ </Tab>
+ <Tab value="bun">
+ ```bash
+ bun install -g @trycua/cli
+ ```
+ </Tab>
</Tabs>
Verify the installation:
diff --git a/docs/content/docs/cua/reference/cloud-cli/index.mdx b/docs/content/docs/cua/reference/cloud-cli/index.mdx
index 6e4d5c3777..31d627f550 100644
--- a/docs/content/docs/cua/reference/cloud-cli/index.mdx
+++ b/docs/content/docs/cua/reference/cloud-cli/index.mdx
@@ -11,9 +11,14 @@ The Cua CLI is a command-line tool for managing your Cua cloud sandboxes. Create
## Installation
<Tabs items={['macOS / Linux', 'Windows']}>
- <Tab value="macOS / Linux">```bash curl -LsSf https://cua.ai/cli/install.sh | sh ```</Tab>
+ <Tab value="macOS / Linux">
+ ```bash
+ curl -LsSf https://cua.ai/cli/install.sh | sh
+ ```
+ </Tab>
<Tab value="Windows">
- ```powershell powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"
+ ```powershell
+ powershell -ExecutionPolicy ByPass -c "irm https://cua.ai/cli/install.ps1 | iex"
```
</Tab>
</Tabs>
diff --git a/docs/scripts/README.md b/docs/scripts/README.md
index 07c32cc02f..5250047006 100644
--- a/docs/scripts/README.md
+++ b/docs/scripts/README.md
@@ -151,6 +151,7 @@ Code indexing uses **parallel sharded processing** for performance:
```
Each component gets its own databases:
+
- `code_index_{component}.sqlite` - FTS5 full-text search
- `code_index_{component}.lancedb/` - Vector embeddings for semantic search
@@ -175,6 +176,7 @@ modal run docs/scripts/modal_app.py --skip-code
The MCP server automatically discovers and queries across all component databases:
**SQLite Queries** - Uses `ATTACH DATABASE` to create a unified view:
+
```sql
-- This queries across ALL component databases
SELECT component, version, file_path
@@ -187,6 +189,7 @@ WHERE code_files_fts MATCH 'ComputerAgent'
```
**Vector Search** - Queries all LanceDBs and merges results by similarity:
+
```python
# Searches all component databases, returns top results
query_code_vectors("screenshot capture implementation", limit=10)
diff --git a/libs/typescript/cua-cli/src/cli.ts b/libs/typescript/cua-cli/src/cli.ts
index bda0c6e35e..605b614c5d 100644
--- a/libs/typescript/cua-cli/src/cli.ts
+++ b/libs/typescript/cua-cli/src/cli.ts
@@ -2,13 +2,30 @@ import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import { registerAuthCommands } from './commands/auth';
import { registerSandboxCommands } from './commands/sandbox';
+import { http } from './http';
+import { getApiKey } from './storage';
+import type { SandboxItem } from './util';
+
+// Fetch sandbox names for shell completion
+async function getSandboxNames(): Promise<string[]> {
+ try {
+ const token = getApiKey();
+ if (!token) return [];
+ const res = await http('/v1/vms', { token });
+ if (!res.ok) return [];
+ const sandboxes = (await res.json()) as SandboxItem[];
+ return sandboxes.map((s) => s.name);
+ } catch {
+ return [];
+ }
+}
export async function runCli() {
let argv = yargs(hideBin(process.argv))
.scriptName('cua')
.usage('Usage: $0 <command> [options]')
.epilogue(
- 'Recommended Command Structure:\n' +
+ 'Commands:\n' +
' cua auth <command> Authenticate and manage credentials\n' +
' login Login via browser or with API key\n' +
' env Export API key to .env file\n' +
@@ -18,12 +35,80 @@ export async function runCli() {
' list View all your sandboxes\n' +
' create Provision a new sandbox\n' +
' get Get detailed info about a sandbox\n' +
- ' start Start or resume a sandbox\n' +
+ ' delete Permanently delete a sandbox\n' +
+ ' start Start a stopped sandbox\n' +
' stop Stop a sandbox (preserves disk)\n' +
+ ' restart Restart/reboot a sandbox\n' +
' suspend Suspend a sandbox (preserves memory)\n' +
' vnc Open remote desktop\n' +
'\n' +
+ ' cua completion Generate shell completion script\n' +
+ '\n' +
'Documentation: https://docs.cua.ai/libraries/cua-cli/commands'
+ )
+ .completion(
+ 'completion',
+ 'Generate shell completion script',
+ async function (current, argv) {
+ // Provide dynamic completions for sandbox names
+ const commands = ['auth', 'sandbox', 'sb', 'completion'];
+ const authCommands = ['login', 'env', 'logout'];
+ const sbCommands = [
+ 'list',
+ 'ls',
+ 'ps',
+ 'create',
+ 'delete',
+ 'start',
+ 'stop',
+ 'restart',
+ 'suspend',
+ 'vnc',
+ 'open',
+ 'get',
+ ];
+
+ // If completing a sandbox name argument
+ const args = process.argv.slice(2);
+ const needsSandboxName = [
+ 'delete',
+ 'start',
+ 'stop',
+ 'restart',
+ 'suspend',
+ 'vnc',
+ 'open',
+ 'get',
+ ];
+
+ // Check if we're completing after a command that needs a sandbox name
+ if (args.length >= 2) {
+ const lastCmd = args[args.length - 2];
+ if (
+ needsSandboxName.includes(lastCmd) ||
+ (args.length >= 3 &&
+ args[0] === 'sb' &&
+ needsSandboxName.includes(args[1]))
+ ) {
+ return await getSandboxNames();
+ }
+ }
+
+ // Top-level completion
+ if (args.length <= 1) {
+ return commands;
+ }
+
+ // Sub-command completion
+ if (args[0] === 'auth') {
+ return authCommands;
+ }
+ if (args[0] === 'sandbox' || args[0] === 'sb') {
+ return sbCommands;
+ }
+
+ return [];
+ }
);
// Override the default --version behavior
argv = argv.version(false).option('version', {
diff --git a/scripts/install-cli.ps1 b/scripts/install-cli.ps1
index b3d8a0df4c..f1637c2ff3 100644
--- a/scripts/install-cli.ps1
+++ b/scripts/install-cli.ps1
@@ -29,6 +29,56 @@ function Get-LatestCuaTag {
return $null
}
+# Install shell completions (idempotent)
+function Install-Completions {
+ param([string]$CuaBinaryPath)
+
+ $completionsDir = "$env:USERPROFILE\.cua\completions"
+ if (-not (Test-Path $completionsDir)) {
+ New-Item -ItemType Directory -Path $completionsDir -Force | Out-Null
+ }
+
+ $completionScript = Join-Path $completionsDir "cua.ps1"
+
+ # Generate completion script
+ try {
+ $completionContent = & $CuaBinaryPath completion 2>$null
+ if ($completionContent) {
+ Set-Content -Path $completionScript -Value $completionContent -Force
+ }
+ } catch {
+ return
+ }
+
+ if (-not (Test-Path $completionScript)) {
+ return
+ }
+
+ # Add to PowerShell profile (idempotent)
+ $profilePath = $PROFILE.CurrentUserAllHosts
+ if (-not $profilePath) {
+ $profilePath = $PROFILE
+ }
+
+ $sourceLine = ". `"$completionScript`""
+
+ # Create profile if it doesn't exist
+ if (-not (Test-Path $profilePath)) {
+ $profileDir = Split-Path $profilePath -Parent
+ if (-not (Test-Path $profileDir)) {
+ New-Item -ItemType Directory -Path $profileDir -Force | Out-Null
+ }
+ New-Item -ItemType File -Path $profilePath -Force | Out-Null
+ }
+
+ # Check if line already exists
+ $profileContent = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
+ if ($profileContent -notlike "*$completionScript*") {
+ Add-Content -Path $profilePath -Value "`n# Cua CLI completions`n$sourceLine"
+ Write-Host "Success: Added shell completions to PowerShell profile" -ForegroundColor Green
+ }
+}
+
function Install-WithBun {
Write-Host "Installing Cua CLI using Bun..." -ForegroundColor Yellow
@@ -69,6 +119,9 @@ function Install-WithBun {
$installDir = "$env:USERPROFILE\.cua\bin"
if (-not (Test-Path $installDir)) { New-Item -ItemType Directory -Path $installDir -Force | Out-Null }
Set-Content -Path (Join-Path $installDir ".version") -Value $bunVersion -NoNewline
+ # Install completions
+ $cuaPath = Get-Command cua -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
+ if ($cuaPath) { Install-Completions -CuaBinaryPath $cuaPath }
return $true
} catch {
Write-Host "Warning: Failed to install with Bun, trying npm..." -ForegroundColor Yellow
@@ -83,6 +136,9 @@ function Install-WithBun {
$installDir = "$env:USERPROFILE\.cua\bin"
if (-not (Test-Path $installDir)) { New-Item -ItemType Directory -Path $installDir -Force | Out-Null }
Set-Content -Path (Join-Path $installDir ".version") -Value $npmVersion -NoNewline
+ # Install completions
+ $cuaPath = Get-Command cua -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
+ if ($cuaPath) { Install-Completions -CuaBinaryPath $cuaPath }
return $true
} catch {
Write-Host "Error: Installation failed with npm as well." -ForegroundColor Red
@@ -163,16 +219,19 @@ if ($currentPath -notlike "*$installDir*") {
Write-Host "Success: Added $installDir to your PATH" -ForegroundColor Green
}
+# Install shell completions
+Install-Completions -CuaBinaryPath $binaryPath
+
# Verify installation
if (Test-Path $binaryPath) {
Write-Host "Success: Cua CLI $version installed successfully to $binaryPath" -ForegroundColor Green
Write-Host ""
Write-Host "Get started with:" -ForegroundColor Cyan
Write-Host " cua login"
- Write-Host " cua create --os linux --configuration small --region north-america"
+ Write-Host " cua create --os linux --size small --region north-america"
Write-Host ""
Write-Host "For more help, visit: https://docs.cua.ai/libraries/cua-cli" -ForegroundColor Cyan
-
+
# Offer to add to PATH if not already there
if (-not ($env:Path -like "*$installDir*")) {
Write-Host ""
diff --git a/scripts/install-cli.sh b/scripts/install-cli.sh
index 932b87a13c..364168de86 100755
--- a/scripts/install-cli.sh
+++ b/scripts/install-cli.sh
@@ -18,22 +18,58 @@ print_success() {
printf "\033[90m📚 For more help, visit: https://docs.cua.ai/libraries/cua-cli\033[0m\n"
}
+# Helper function to add line to profile if not present (idempotent)
+add_to_profile_if_missing() {
+ local file="$1"
+ local line="$2"
+ local description="$3"
+
+ if [ -f "$file" ]; then
+ if ! grep -qF "$line" "$file" 2>/dev/null; then
+ echo "$line" >> "$file"
+ echo "$description"
+ fi
+ fi
+}
+
+# Install shell completions (idempotent)
+install_completions_for_path() {
+ local cua_bin="$1"
+ local COMPLETIONS_DIR="$HOME/.cua/completions"
+ mkdir -p "$COMPLETIONS_DIR"
+
+ # Generate completions script
+ local COMPLETION_SCRIPT="$COMPLETIONS_DIR/cua.bash"
+ "$cua_bin" completion > "$COMPLETION_SCRIPT" 2>/dev/null || true
+
+ if [ -s "$COMPLETION_SCRIPT" ]; then
+ local SOURCE_LINE="[ -f \"$COMPLETION_SCRIPT\" ] && source \"$COMPLETION_SCRIPT\""
+
+ add_to_profile_if_missing "$HOME/.bashrc" "$SOURCE_LINE" "Added shell completions to ~/.bashrc"
+
+ # For zsh, also add to .zshrc
+ if [ -f "$HOME/.zshrc" ]; then
+ add_to_profile_if_missing "$HOME/.zshrc" "$SOURCE_LINE" "Added shell completions to ~/.zshrc"
+ fi
+ fi
+}
+
# Function to install with bun as fallback
install_with_bun() {
echo "📦 Installing Cua CLI using Bun..."
-
+
# Check if bun is already installed
if ! command -v bun &> /dev/null; then
echo "📦 Installing Bun..."
curl -fsSL https://bun.sh/install | bash
-
+
# Source the shell profile to make bun available
if [ -f "$HOME/.bashrc" ]; then
source "$HOME/.bashrc"
elif [ -f "$HOME/.zshrc" ]; then
source "$HOME/.zshrc"
fi
-
+
# Add bun to PATH for this session
export PATH="$HOME/.bun/bin:$PATH"
fi
@@ -70,6 +106,8 @@ install_with_bun() {
local INSTALL_DIR="$HOME/.cua/bin"
mkdir -p "$INSTALL_DIR"
echo "$VERSION_BUN" > "$INSTALL_DIR/.version"
+ # Install completions
+ install_completions_for_path "$(command -v cua)"
# Print success and exit
print_success "$(command -v cua)" "$VERSION_BUN" "$config_file"
exit 0
@@ -188,28 +226,24 @@ chmod +x "$INSTALL_DIR/cua"
# Write version file
echo "$VERSION" > "$INSTALL_DIR/.version"
-# Add ~/.cua/bin to PATH if not already in PATH
+# Add ~/.cua/bin to PATH if not already in PATH (idempotent)
+PATH_EXPORT="export PATH=\"$INSTALL_DIR:\$PATH\""
+
if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
- # Add to .bashrc, .zshrc, or .profile
- if [ -f "$HOME/.bashrc" ]; then
- echo "export PATH=\"$INSTALL_DIR:\$PATH\"" >> "$HOME/.bashrc"
- echo "Added $INSTALL_DIR to PATH in ~/.bashrc"
- fi
-
- if [ -f "$HOME/.zshrc" ]; then
- echo "export PATH=\"$INSTALL_DIR:\$PATH\"" >> "$HOME/.zshrc"
- echo "Added $INSTALL_DIR to PATH in ~/.zshrc"
- fi
-
- if [ -f "$HOME/.profile" ] && [ ! -f "$HOME/.bashrc" ] && [ ! -f "$HOME/.zshrc" ]; then
- echo "export PATH=\"$INSTALL_DIR:\$PATH\"" >> "$HOME/.profile"
- echo "Added $INSTALL_DIR to PATH in ~/.profile"
+ add_to_profile_if_missing "$HOME/.bashrc" "$PATH_EXPORT" "Added $INSTALL_DIR to PATH in ~/.bashrc"
+ add_to_profile_if_missing "$HOME/.zshrc" "$PATH_EXPORT" "Added $INSTALL_DIR to PATH in ~/.zshrc"
+
+ if [ ! -f "$HOME/.bashrc" ] && [ ! -f "$HOME/.zshrc" ]; then
+ add_to_profile_if_missing "$HOME/.profile" "$PATH_EXPORT" "Added $INSTALL_DIR to PATH in ~/.profile"
fi
-
+
# Add to current session
export PATH="$INSTALL_DIR:$PATH"
fi
+# Install shell completions
+install_completions_for_path "$INSTALL_DIR/cua"
+
# Verify installation
if command -v cua &> /dev/null; then
# Determine which config file was updated