Skip to main content

​
CLI Overview

The caged CLI is the primary way to create and manage sandboxes from your terminal.

​
Installation

brew install caged-dev/tap/caged
Verify the installation: 
caged version

​
Authentication

caged auth login
This opens your browser to authenticate. After logging in, the CLI stores your token locally. Alternatively, set the CAGED_API_KEY environment variable: 
export CAGED_API_KEY=caged_sk_...

​
Configuration

The CLI reads configuration from:
  1. Command-line flags (highest priority)
  2. .caged.yaml in the current directory
  3. ~/.config/caged/config.yaml (global defaults)
  4. Environment variables (CAGED_*)

​
Global Config

# ~/.config/caged/config.yaml
api_url: https://api.caged.dev
default_template: node-20
default_cpus: 2
default_memory: 1024

​
Project Config

See Config-as-Code for the full .caged.yaml reference.

​
Output Formats

The CLI supports multiple output formats: 
caged sandboxes list --format json   # JSON output
caged sandboxes list --format table  # Table (default)
caged sandboxes list --format yaml   # YAML output

​
Autocomplete

# Bash
caged completion bash > /etc/bash_completion.d/caged

# Zsh
caged completion zsh > "${fpath[1]}/_caged"

# Fish
caged completion fish > ~/.config/fish/completions/caged.fish