CLI Overview

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

Installation

brew tap caged-dev/tap
brew install caged

curl -fsSL https://get.caged.dev | sh

go install github.com/caged-dev/cli/cmd/caged@latest

Verify the installation:

caged version

Authentication

caged login

This prompts for your API URL and API key. After entering your credentials, the CLI stores them locally at ~/.config/caged/config.json.

Alternatively, set the CAGED_API_KEY environment variable:

export CAGED_API_KEY=caged_...

Configuration

The CLI reads configuration from:

1. Command-line flags (highest priority)
2. .caged.yaml in the current directory
3. ~/.config/caged/config.json (credentials)
4. Environment variables (CAGED_*)

Credentials

// ~/.config/caged/config.json
{
  "api_url": "https://api.caged.dev",
  "api_key": "caged_..."
}

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