---
title: CLI Overview
description: "Install and configure the Caged CLI."
---

# CLI Overview

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

## Installation

<CodeGroup>

```bash title="macOS (Homebrew)"
brew tap caged-dev/tap
brew install caged
```

```bash title="Linux"
curl -fsSL https://get.caged.dev | sh
```

```bash title="Go Install"
go install github.com/caged-dev/cli/cmd/caged@latest
```

</CodeGroup>

Verify the installation:

```bash
caged version
```

## Authentication

```bash
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:

```bash
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

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

### Project Config

See [Config-as-Code](/guides/config-as-code) for the full `.caged.yaml` reference.

## Output Formats

The CLI supports multiple output formats:

```bash
caged sandboxes list --format json   # JSON output
caged sandboxes list --format table  # Table (default)
caged sandboxes list --format yaml   # YAML output
```

## Autocomplete

```bash
# 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
```