> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
# 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 theme={null}
caged sandboxes list [flags]
```

| Flag       | Description                    | Default |
| ---------- | ------------------------------ | ------- |
| `--format` | Output format: `table`, `json` | `table` |

**Examples:**

```bash theme={null}
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 theme={null}
[
  {
    "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 theme={null}
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 theme={null}
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 theme={null}
caged sandboxes connect <sandbox-id>
```

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 theme={null}
caged sandboxes exec <sandbox-id> <command>
```

**Examples:**

```bash theme={null}
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 theme={null}
caged sandboxes sleep <sandbox-id>
```

### caged sandboxes wake

Resume a sleeping sandbox. Alias: `caged wake`.

```bash theme={null}
caged sandboxes wake <sandbox-id>
```

### caged sandboxes destroy

Destroy a sandbox permanently. Alias: `caged destroy`, `caged rm`.

```bash theme={null}
caged sandboxes destroy <sandbox-id>
```

### caged sandboxes logs

View sandbox event logs. Alias: `caged logs`.

```bash theme={null}
caged sandboxes logs <sandbox-id> [flags]
```

| Flag | Description                    |
| ---- | ------------------------------ |
| `-f` | Follow log output in real-time |

```bash theme={null}
caged sandboxes logs cage_abc123
caged sandboxes logs -f cage_abc123
```

***

## 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 theme={null}
caged mcp <sandbox-id>
```

Add it to your MCP client configuration:

```json theme={null}
{
  "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 <sandbox-id>` first if
it's sleeping.

***

## caged version

Print CLI version.

```bash theme={null}
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 <id>`    | `caged sandboxes connect <id>`    |
| `caged exec <id> <cmd>` | `caged sandboxes exec <id> <cmd>` |
| `caged destroy <id>`    | `caged sandboxes destroy <id>`    |
| `caged rm <id>`         | `caged sandboxes destroy <id>`    |
| `caged sleep <id>`      | `caged sandboxes sleep <id>`      |
| `caged wake <id>`       | `caged sandboxes wake <id>`       |
| `caged logs <id>`       | `caged sandboxes logs <id>`       |

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 theme={null}
caged policy list
```

### caged policy templates

Show available policy templates.

```bash theme={null}
caged policy templates
```

### caged policy apply

Apply a built-in template to your account.

```bash theme={null}
caged policy apply <template>
```

Templates: `soc2`, `hipaa`, `dev-only`, `restrictive`, `permissive`

### caged policy delete

Delete a policy by ID.

```bash theme={null}
caged policy delete <policy-id>
```

***

## caged eval

Manage agent eval scenarios and runs (Cage Eval).

### caged eval list

List all eval scenarios.

```bash theme={null}
caged eval list
```

### caged eval load

Load scenarios from a YAML file. Supports suite files (`.caged-eval.yaml`) and single scenario files (`*.scenario.yaml`).

```bash theme={null}
caged eval load <file.yaml>
```

### caged eval discover

Find eval scenario files in a directory.

```bash theme={null}
caged eval discover [directory]
```

### caged eval run

Run a specific scenario.

```bash theme={null}
caged eval run <scenario-id>
```

### caged eval flakiness

Run a scenario multiple times to detect flakiness.

```bash theme={null}
caged eval flakiness <scenario-id> [--iterations 10]
```

### caged eval regression

Detect performance regression against baseline runs.

```bash theme={null}
caged eval regression <scenario-id>
```

### caged eval runs

List run history for a scenario.

```bash theme={null}
caged eval runs <scenario-id>
```

### caged eval delete

Delete a scenario.

```bash theme={null}
caged eval delete <scenario-id>
```