CLI
View as Markdown Open in ChatGPT Open in Claude

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.

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):

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.

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:

# 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.

caged sandboxes list [flags]
Flag Description Default
--format Output format: table, json table

Examples:

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:

[
  {
    "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.

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:

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.

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.

caged sandboxes exec <sandbox-id> <command>

Examples:

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.

caged sandboxes sleep <sandbox-id>

caged sandboxes wake

Resume a sleeping sandbox. Alias: caged wake.

caged sandboxes wake <sandbox-id>

caged sandboxes destroy

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

caged sandboxes destroy <sandbox-id>

caged sandboxes logs

View sandbox event logs. Alias: caged logs.

caged sandboxes logs <sandbox-id> [flags]
Flag Description
-f Follow log output in real-time 
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.

caged pipeline list [flags]
Flag Description Default
--format Output format: table, json table

Example:

caged pipeline list
caged pipeline list --format json

caged pipeline get

Get details of a specific pipeline.

caged pipeline get <pipeline-id>

caged pipeline run

Start a new run of a pipeline.

caged pipeline run <pipeline-name-or-id> [flags]
Flag Description
--env Environment variables (KEY=VAL,KEY2=VAL2)
--repo Git repository URL
--branch Git branch

Examples:

# 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.

caged pipeline runs <pipeline-id> [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.

caged pipeline cancel <pipeline-id> <run-id>

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.

caged pipeline state list <pipeline-id> <run-id> [flags]
Flag Description Default
--format Output format: table, json table

Example:

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.

caged pipeline state get <pipeline-id> <run-id> <key>

Example:

caged pipeline state get pipe-abc123 run-xyz789 analysis_results

Output:

{
  "files": ["src/main.ts", "src/utils.ts"],
  "score": 85,
  "issues": []
}

caged pipeline state set

Create or update a state entry.

caged pipeline state set <pipeline-id> <run-id> <key> [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:

# 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.

caged pipeline state delete <pipeline-id> <run-id> <key>

Example:

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.

caged mcp <sandbox-id>

Add it to your MCP client configuration:

{
  "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.

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.

caged policy list

caged policy templates

Show available policy templates.

caged policy templates

caged policy apply

Apply a built-in template to your account.

caged policy apply <template>

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

caged policy delete

Delete a policy by ID.

caged policy delete <policy-id>

caged eval

Manage agent eval scenarios and runs (Cage Eval).

caged eval list

List all eval scenarios.

caged eval list

caged eval load

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

caged eval load <file.yaml>

caged eval discover

Find eval scenario files in a directory.

caged eval discover [directory]

caged eval run

Run a specific scenario.

caged eval run <scenario-id>

caged eval flakiness

Run a scenario multiple times to detect flakiness.

caged eval flakiness <scenario-id> [--iterations 10]

caged eval regression

Detect performance regression against baseline runs.

caged eval regression <scenario-id>

caged eval runs

List run history for a scenario.

caged eval runs <scenario-id>

caged eval delete

Delete a scenario.

caged eval delete <scenario-id>
Was this page helpful?