🛰️ export from upstream (251518c)

docs/commands.md

@@ -0,0 +1,223 @@
+# 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.