--- title: CLI Commands description: "Complete reference for all Caged CLI commands." --- # CLI Commands The Caged CLI organizes commands into groups. The main sandbox management commands are under `caged sandboxes`, with shortcut aliases available for convenience. ## caged login Authenticate with your Caged account via browser. ```bash caged login ``` Opens your browser to `caged.dev/auth/device` where you approve the CLI access. The CLI automatically receives your credentials once approved — no manual key copying needed. ``` $ caged login Logging in to Caged... Your code: ABCD-EFGH Opening browser to: https://caged.dev/auth/device?code=ABCD-EFGH Waiting for authorization... Logged in as josh@bytangle.com Credentials saved to ~/.config/caged/config.json ``` ### Manual login (API key) If you prefer to paste an API key directly (CI environments, headless servers): ```bash caged login --manual ``` Prompts for your API URL and API key interactively. Stores credentials at `~/.config/caged/config.json`. ## caged up Create a sandbox from `.caged.yaml` in the current directory. ```bash caged up [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--template` | Override base image | from config | | `--cpus` | Override vCPU count | from config | | `--memory` | Override memory in MB | from config | | `--disk` | Override disk in GB | from config | | `--repo` | Git repo URL to clone | — | | `--repo-token` | PAT/OAuth token for private repos | — | | `--repo-branch` | Branch to checkout | main | | `--repo-commit` | Specific commit SHA | — | | `--repo-subdir` | Monorepo subdirectory to extract | — | | `--budget` | Max spend in USD | — | | `--network` | Network mode: full, none, allowlist | from config | | `--allowlist` | Comma-separated host allowlist | — | | `--env` | Environment variables (KEY=VAL,KEY2=VAL2) | — | | `--packages` | Packages to pre-install (comma-separated) | — | | `--agents` | AI agents to install (claude, aider, codex) | — | | `--config` | Path to config file | `.caged.yaml` | **Examples:** ```bash # From .caged.yaml in current directory caged up # Override template and budget caged up --template python-312 --budget 10 # Clone a private repo with Claude Code caged up --template node-20 \ --repo https://github.com/your-org/private-repo \ --repo-token $GITHUB_TOKEN \ --agents claude # Clone a specific branch caged up --repo https://github.com/user/project --repo-branch develop # With custom config file caged up --config ./sandbox.yaml ``` --- ## caged sandboxes The `sandboxes` command group manages sandbox lifecycle. ### caged sandboxes list List all sandboxes. Alias: `caged list`, `caged ls`. ```bash caged sandboxes list [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--format` | Output format: `table`, `json` | `table` | **Examples:** ```bash caged sandboxes list caged sandboxes list --format json ``` **Table output:** ``` ID STATUS TEMPLATE CPUs MEMORY CREATED cage_abc123 running node-20 2 1024MB 2024-01-15T10:30:00Z cage_def456 sleeping python-3.12 4 2048MB 2024-01-14T08:00:00Z ``` **JSON output:** ```json [ { "id": "cage_abc123", "status": "running", "template": "node-20", "cpus": 2, "memory_mb": 1024, "created_at": "2024-01-15T10:30:00Z" } ] ``` ### caged sandboxes create Create and start a new sandbox. Alias: `caged run`. ```bash caged sandboxes create [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--template` | Base image | `node-20` | | `--cpus` | vCPU count | `2` | | `--memory` | Memory in MB | `512` | | `--disk` | Disk in GB | `5` | | `--network` | Network mode: full, none, allowlist | `full` | | `--allowlist` | Comma-separated host allowlist | — | | `--repo` | Git repo to clone | — | | `--env` | Environment variables (KEY=VAL,KEY2=VAL2) | — | | `--budget` | Max spend in USD | — | **Examples:** ```bash caged sandboxes create --template node-20 --cpus 2 --memory 1024 caged sandboxes create --template python-3.12 --budget 5 --repo https://github.com/user/project caged sandboxes create --network allowlist --allowlist "registry.npmjs.org,github.com" ``` ### caged sandboxes connect Connect to a running sandbox's interactive terminal. Alias: `caged connect`. ```bash caged sandboxes connect ``` Opens a full interactive terminal (real PTY over WebSocket) — like `ssh` into the sandbox. Output streams live, so long-running commands and AI agents show their progress in real time. Arrow keys, tab completion, Ctrl+C, colors, and terminal resizing all work. ``` Connected to sandbox cage_abc123 (node-20). Type 'exit' or press Ctrl+D to disconnect. root@caged-sandbox:~# npm test ✓ All tests passed root@caged-sandbox:~# exit ``` For non-interactive/scripted use, prefer `caged exec`. ### caged sandboxes exec Execute a single command in a sandbox and return the output. Alias: `caged exec`. ```bash caged sandboxes exec ``` **Examples:** ```bash caged sandboxes exec cage_abc123 "npm test" caged sandboxes exec cage_abc123 "cat package.json" caged sandboxes exec cage_abc123 "git status" ``` ### caged sandboxes sleep Pause a running sandbox. No compute charges while sleeping. Alias: `caged sleep`. ```bash caged sandboxes sleep ``` ### caged sandboxes wake Resume a sleeping sandbox. Alias: `caged wake`. ```bash caged sandboxes wake ``` ### caged sandboxes destroy Destroy a sandbox permanently. Alias: `caged destroy`, `caged rm`. ```bash caged sandboxes destroy ``` ### caged sandboxes logs View sandbox event logs. Alias: `caged logs`. ```bash caged sandboxes logs [flags] ``` | Flag | Description | |------|-------------| | `-f` | Follow log output in real-time | ```bash caged sandboxes logs cage_abc123 caged sandboxes logs -f cage_abc123 ``` --- ## caged pipeline Manage pipelines and pipeline runs. ### caged pipeline list List all pipelines for your account. ```bash caged pipeline list [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--format` | Output format: `table`, `json` | `table` | **Example:** ```bash caged pipeline list caged pipeline list --format json ``` ### caged pipeline get Get details of a specific pipeline. ```bash caged pipeline get ``` ### caged pipeline run Start a new run of a pipeline. ```bash caged pipeline run [flags] ``` | Flag | Description | |------|-------------| | `--env` | Environment variables (KEY=VAL,KEY2=VAL2) | | `--repo` | Git repository URL | | `--branch` | Git branch | **Examples:** ```bash # Run a pipeline with environment variables caged pipeline run agent-feature --env FEATURE_SPEC="Add dark mode toggle" # Run with a specific repo caged pipeline run ci-pipeline --repo https://github.com/org/app --branch develop ``` ### caged pipeline runs List runs for a pipeline. ```bash caged pipeline runs [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--limit` | Max number of runs to return | 20 | | `--format` | Output format: `table`, `json` | `table` | ### caged pipeline cancel Cancel a running pipeline run. ```bash caged pipeline cancel ``` --- ## caged pipeline state Manage the shared state store for a pipeline run. State entries allow stages to share data (analysis results, artifacts, configuration) without committing to git. ### caged pipeline state list List all state entries for a run. ```bash caged pipeline state list [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--format` | Output format: `table`, `json` | `table` | **Example:** ```bash caged pipeline state list pipe-abc123 run-xyz789 ``` **Output:** ``` KEY TYPE SIZE CREATED BY EXPIRES analysis_results json 1.2 KB analyze 2026-08-09T10:05:30Z build_config json 256 B setup 2026-08-09T10:04:00Z status string 12 B api 2026-08-03T10:10:00Z ``` ### caged pipeline state get Get a single state entry. ```bash caged pipeline state get ``` **Example:** ```bash caged pipeline state get pipe-abc123 run-xyz789 analysis_results ``` **Output:** ```json { "files": ["src/main.ts", "src/utils.ts"], "score": 85, "issues": [] } ``` ### caged pipeline state set Create or update a state entry. ```bash caged pipeline state set [value] [flags] ``` | Flag | Description | Default | |------|-------------|---------| | `--type` | Value type: `string`, `json`, `file`, `patch`, `artifact` | `string` | | `--ttl` | TTL in seconds (max 2592000 = 30 days) | 604800 (7 days) | | `--mime-type` | MIME type for file/artifact types | — | | `-f` | Read value from file | — | **Examples:** ```bash # Set a simple string caged pipeline state set pipe-abc123 run-xyz789 status "completed" # Set JSON data caged pipeline state set pipe-abc123 run-xyz789 config '{"debug": true}' --type json # Set from file caged pipeline state set pipe-abc123 run-xyz789 report -f ./analysis-report.json --type json # Set with custom TTL (1 hour) caged pipeline state set pipe-abc123 run-xyz789 temp_cache '{"hot": true}' --type json --ttl 3600 # Set a file reference caged pipeline state set pipe-abc123 run-xyz789 artifact ./dist/app.zip --type file ``` ### caged pipeline state delete Delete a state entry. ```bash caged pipeline state delete ``` **Example:** ```bash caged pipeline state delete pipe-abc123 run-xyz789 temp_cache ``` ### State Limits | Limit | Value | |-------|-------| | Max key length | 256 characters | | Max value size | 1 MB | | Max entries per run | 100 | | Max total size per run | 10 MB | | Default TTL | 7 days | | Max TTL | 30 days | --- ## caged mcp Run a Model Context Protocol server over stdio, bridged to a running sandbox. MCP clients like Claude Desktop and Cursor spawn this command locally — no WebSocket setup or session tokens required. ```bash caged mcp ``` Add it to your MCP client configuration: ```json { "mcpServers": { "caged": { "command": "caged", "args": ["mcp", "cage_abc123"] } } } ``` The AI client gets sandbox tools (`filesystem_read`, `filesystem_write`, `terminal_exec`, `git_commit`, and more) that execute inside the isolated VM. The sandbox must be running — wake it with `caged wake ` first if it's sleeping. --- ## caged version Print CLI version. ```bash caged version ``` --- ## Shortcut Aliases For convenience, sandbox commands have shortcuts at the top level: | Shortcut | Equivalent | |----------|------------| | `caged list` | `caged sandboxes list` | | `caged ls` | `caged sandboxes list` | | `caged run` | `caged sandboxes create` | | `caged connect ` | `caged sandboxes connect ` | | `caged exec ` | `caged sandboxes exec ` | | `caged destroy ` | `caged sandboxes destroy ` | | `caged rm ` | `caged sandboxes destroy ` | | `caged sleep ` | `caged sandboxes sleep ` | | `caged wake ` | `caged sandboxes wake ` | | `caged logs ` | `caged sandboxes logs ` | These shortcuts are provided for backward compatibility and convenience. Both forms work identically. --- ## caged policy Manage security policies (Cage Rules). ### caged policy list List all policies for your account. ```bash caged policy list ``` ### caged policy templates Show available policy templates. ```bash caged policy templates ``` ### caged policy apply Apply a built-in template to your account. ```bash caged policy apply