# Command Reference

Sandcage provides subcommands for running AI coding agents in isolated Docker containers.

```
sandcage <COMMAND> [OPTIONS]
```

---

## claude

Run the Claude Code agent in a sandboxed container.

```
sandcage claude [OPTIONS] [-- AGENT_ARGS...]
```

**Options:**

| Flag | Description |
|------|-------------|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
| `--shell` | Drop into a shell instead of launching the agent |

**Trailing arguments:** Any arguments after `--` are forwarded directly to the Claude Code binary inside the container.

**Examples:**

```sh
# Run Claude Code on the current directory
sandcage claude

# Run Claude Code on a specific project
sandcage claude --path /home/user/myproject

# Drop into a shell in the Claude container environment
sandcage claude --shell

# Forward arguments to the agent
sandcage claude -- --resume
```

---

## codex

Run the OpenAI Codex agent in a sandboxed container.

```
sandcage codex [OPTIONS] [-- AGENT_ARGS...]
```

**Options:**

| Flag | Description |
|------|-------------|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
| `--shell` | Drop into a shell instead of launching the agent |

**Trailing arguments:** Any arguments after `--` are forwarded directly to the Codex binary inside the container.

**Examples:**

```sh
# Run Codex on the current directory
sandcage codex

# Forward arguments to Codex
sandcage codex -- --model o4-mini
```

---

## gemini

Run the Gemini CLI agent in a sandboxed container.

```
sandcage gemini [OPTIONS] [-- AGENT_ARGS...]
```

**Options:**

| Flag | Description |
|------|-------------|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
| `--shell` | Drop into a shell instead of launching the agent |

**Trailing arguments:** Any arguments after `--` are forwarded directly to the Gemini CLI binary inside the container.

**Examples:**

```sh
# Run Gemini CLI on the current directory
sandcage gemini

# Drop into a shell in the Gemini container
sandcage gemini --shell
```

---

## shell

Open an interactive shell (zsh) with the same sandboxed environment used by agents.

```
sandcage shell [OPTIONS]
```

**Options:**

| Flag | Description |
|------|-------------|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |

**Examples:**

```sh
# Interactive shell in the sandbox for current project
sandcage shell

# Interactive shell for a specific project
sandcage shell --path /home/user/myproject
```

---

## build

Build the container images used by sandcage services.

```
sandcage build [OPTIONS] [SERVICES...]
```

**Options:**

| Flag | Description |
|------|-------------|
| `-f, --force` | Force rebuild even if images are up to date |

**Positional arguments:** Optionally specify which services to build (e.g. `claude`, `codex`, `gemini`). When omitted, all enabled services are built.

**Examples:**

```sh
# Build all enabled service images
sandcage build

# Force rebuild of all images
sandcage build --force

# Build only the claude image
sandcage build claude

# Build claude and gemini images
sandcage build claude gemini
```

---

## init

Initialize a `.sandcage.yml` configuration file for a project.

```
sandcage init
```

Scaffolds a project configuration in the current workspace directory. No options.

**Examples:**

```sh
# Initialize sandcage config in current directory
sandcage init
```

---

## setup ssh

Configure SSH key access for containers. Copies selected SSH keys into a Docker volume accessible by sandcage containers.

```
sandcage setup ssh [OPTIONS]
```

**Options:**

| Flag | Description |
|------|-------------|
| `--global` | Write to global config (`~/.sandcage/config.toml`) instead of project config |
| `--yes` | Skip confirmation prompt |
| `--refresh` | Re-populate the SSH volume using the previously saved selection |
| `--bind` | Use legacy full bind mount instead of volume copy |

**Examples:**

```sh
# Interactive SSH key setup for the current project
sandcage setup ssh

# Non-interactive setup writing to global config
sandcage setup ssh --global --yes

# Refresh the SSH volume after adding new keys
sandcage setup ssh --refresh
```

---

## Common Patterns

**Project path resolution:** All agent commands and `shell` accept `--path` (`-p`) to specify the project directory. When omitted, sandcage resolves the workspace from the current directory.

**Shell override:** The `--shell` flag on agent commands (`claude`, `codex`, `gemini`) drops you into an interactive shell inside the agent's container without launching the agent itself. Useful for debugging the container environment.

**Forwarding arguments to agents:** Agent commands accept trailing arguments (after `--`) that are passed through to the underlying agent binary. This allows setting agent-specific flags without sandcage needing to know about them.

**Available services:** The built-in services are `claude`, `codex`, `gemini`, and `shell`. Each agent service auto-installs its binary on first run if not already present in the container.