# CLI reference

Complete reference for Moat CLI commands.

## Global flags

These flags apply to all commands:

| Flag | Description |
|------|-------------|
| `-v`, `--verbose` | Enable verbose output (debug logs) |
| `--dry-run` | Show what would happen without executing |
| `--json` | Output in JSON format |
| `--profile NAME` | Credential profile to use (env: `MOAT_PROFILE`) |
| `-h`, `--help` | Show help for command |

## Run identification

Commands that operate on a run (`stop`, `destroy`, `logs`, `trace`, `audit`, `snapshot`) accept a run ID or a run name:

```bash
moat stop run_a1b2c3d4e5f6   # by full ID
moat stop run_a1b2                # by ID prefix
moat stop my-agent                # by name
```

Resolution priority: exact ID > ID prefix > exact name.

If a name matches multiple runs, batch commands (`stop`, `destroy`) prompt for confirmation while single-target commands (`logs`) list the matches and ask you to specify a run ID.

## Common agent flags

The agent commands (`moat claude`, `moat codex`, `moat gemini`) share the following flags. These flags work identically across `moat claude`, `moat codex`, and `moat gemini`.

| Flag | Description |
|------|-------------|
| `-g`, `--grant PROVIDER` | Inject credential (repeatable). See [Grants reference](/moat/reference/grants) for available providers. |
| `-e`, `--env KEY=VALUE` | Set environment variable (repeatable) |
| `-m`, `--mount SOURCE:TARGET[:MODE]` | Additional mount (repeatable). See [Mounts reference](/moat/reference/mounts). |
| `-n`, `--name NAME` | Run name (default: from `moat.yaml` or random) |
| `--rebuild` | Force rebuild of container image |
| `--allow-host HOST` | Additional hosts to allow network access to (repeatable) |
| `--runtime RUNTIME` | Container runtime to use (`apple`, `docker`) |
| `--keep` | Keep container after run completes |
| `--no-clipboard` | Disable host clipboard bridging for this run |
| `--no-sandbox` | Disable gVisor sandbox (Docker only) |
| `--tty-trace FILE` | Capture terminal I/O to file for debugging (e.g., `session.json`) |
| `--worktree BRANCH` | Run in a git worktree for this branch (alias: `--wt`) |

Agent commands run interactively by default, owning the terminal with stdin/stdout/stderr connected. Use `-p`/`--prompt` for non-interactive mode (output streams to the terminal). Each agent command also accepts command-specific flags documented in their own sections.

All agent commands support passing an initial prompt after `--`. Unlike `-p`, which runs non-interactively and exits when done, arguments after `--` start an interactive session with the prompt pre-filled:

```bash
moat claude -- "is this thing on?"
moat codex -- "explain this codebase"
```

---

## moat init

Auto-generate a `moat.yaml` configuration file for an existing project.

```
moat init [workspace]
```

Scans the project workspace to detect file types, manifest files, and CI configurations, then runs an AI agent in a bootstrap container to generate an appropriate `moat.yaml`.

### Auto-detection

`moat init` automatically detects which agent credentials are available, in order: Claude, Codex, Gemini. It uses the first agent with valid credentials.

If no credentials are found, the command prints instructions for granting credentials.

### Arguments

| Argument | Description |
|----------|-------------|
| `workspace` | Project directory to analyze (default: current directory) |

### Examples

```bash
# Generate moat.yaml for the current directory
moat init

# Generate moat.yaml for a specific project
moat init /path/to/project
```

---

## moat run

Run an agent in a container.

```
moat run [flags] [path] [-- command]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `path` | Workspace directory (default: current directory) |
| `command` | Command to run (overrides moat.yaml) |

### Flags

| Flag | Description |
|------|-------------|
| `-n`, `--name NAME` | Set run name (used for hostname routing) |
| `-g`, `--grant PROVIDER` | Inject credential (repeatable) |
| `-e`, `--env KEY=VALUE` | Set environment variable (repeatable) |
| `-m`, `--mount SOURCE:TARGET[:MODE]` | Additional mount (repeatable). See [Mounts reference](/moat/reference/mounts). |
| `-i`, `--interactive` | Enable interactive mode (stdin + TTY) |
| `--rebuild` | Force rebuild of container image |
| `--runtime RUNTIME` | Container runtime to use (apple, docker) |
| `--keep` | Keep container after run completes |
| `--no-clipboard` | Disable host clipboard bridging for this run |
| `--no-sandbox` | Disable gVisor sandboxing (Docker only) |
| `--tty-trace FILE` | Capture terminal I/O to file for debugging (e.g., `session.json`) |

### Execution modes

**Non-interactive (default):** Output streams to the terminal. Press `Ctrl+C` to stop.

```bash
moat run ./my-project
```

**Interactive (`-i`):** The run owns the terminal with stdin/stdout/stderr connected and a TTY allocated. Press `Ctrl-/ k` to stop the run. `Ctrl+C` is forwarded to the container process.

```bash
moat run -i -- bash
```

### Examples

```bash
# Run in current directory
moat run

# Run in specific directory
moat run ./my-project

# Run with credentials
moat run --grant github ./my-project

# Run with custom command
moat run -- npm test

# Run shell command
moat run -- sh -c "npm install && npm test"

# Interactive shell
moat run -i -- bash

# Multiple credentials
moat run --grant github --grant anthropic ./my-project

# Environment variable
moat run -e DEBUG=true ./my-project

# Named run for hostname routing
moat run --name my-feature ./my-project

# Disable gVisor sandbox (when needed for compatibility)
moat run --no-sandbox ./my-project
```

### --no-clipboard

Disables host clipboard bridging for this run. Overrides `clipboard: true` in moat.yaml.

```bash
moat run --no-clipboard ./my-project
```

### --no-sandbox

Disables gVisor sandboxing for Docker containers. By default, Moat runs Docker containers with gVisor (`runsc`) for additional isolation. This flag disables gVisor and uses the standard Docker runtime (`runc`).

**When to use:** Some workloads use syscalls that gVisor doesn't support. If your agent fails with syscall-related errors, try `--no-sandbox`.

**Note:** This flag only affects Docker containers. Apple containers use macOS virtualization and are unaffected.

```bash
moat run --no-sandbox ./my-project
```

---

## moat claude

Run Claude Code in a container.

```
moat claude [workspace] [flags] [-- initial-prompt]
```

In addition to the command-specific flags below, `moat claude` accepts all [common agent flags](#common-agent-flags).

### Arguments

| Argument | Description |
|----------|-------------|
| `workspace` | Workspace directory (default: current directory) |
| `initial-prompt` | Text after `--` is passed to Claude as an initial prompt (interactive mode) |

### Command-specific flags

| Flag | Description |
|------|-------------|
| `-p`, `--prompt TEXT` | Run non-interactive with prompt |
| `-c`, `--continue` | Continue the most recent conversation |
| `-r`, `--resume RUN\|UUID` | Resume a specific session by moat run name/ID or raw Claude session UUID |
| `--noyolo` | Restore Claude Code's per-operation confirmation prompts. By default, `moat claude` runs with `--dangerously-skip-permissions` because the container provides isolation. Use `--noyolo` to re-enable permission prompts. |

### Examples

```bash
# Interactive Claude Code
moat claude

# In specific directory
moat claude ./my-project

# Interactive with initial prompt (Claude stays open)
moat claude -- "is this thing on?"
moat claude ./my-project -- "explain this codebase"

# Non-interactive with prompt (exits when done)
moat claude -p "fix the failing tests"

# Continue the most recent conversation
moat claude --continue
moat claude -c

# Resume a specific session by run name
moat claude --resume my-feature

# Resume by raw Claude session UUID
moat claude --resume ae150251-d90a-4f85-a9da-2281e8e0518d

# With GitHub access
moat claude --grant github

# Named run
moat claude --name feature-auth ./my-project

# Run in a git worktree (non-interactive with prompt)
moat claude --worktree=dark-mode --prompt "implement dark mode"

# Require manual approval for each tool use
moat claude --noyolo
```

---

## moat codex

Run OpenAI Codex CLI in a container.

```
moat codex [workspace] [flags] [-- initial-prompt]
```

In addition to the command-specific flags below, `moat codex` accepts all [common agent flags](#common-agent-flags).

### Arguments

| Argument | Description |
|----------|-------------|
| `workspace` | Workspace directory (default: current directory) |
| `initial-prompt` | Text after `--` is passed to Codex as an initial prompt (interactive mode) |

### Command-specific flags

| Flag | Description |
|------|-------------|
| `-p`, `--prompt TEXT` | Run non-interactive with prompt |
| `--full-auto` | Enable full-auto mode (auto-approve tool use). Default: `true`. Set `--full-auto=false` to require manual approval for each action. This is analogous to `--noyolo` on `moat claude` -- the container provides isolation, so auto-approval is the default. |

### Examples

```bash
# Interactive Codex CLI
moat codex

# In specific directory
moat codex ./my-project

# Interactive with initial prompt (Codex stays open)
moat codex -- "testing"
moat codex ./my-project -- "explain this codebase"

# Non-interactive with prompt (exits when done)
moat codex -p "explain this codebase"
moat codex -p "fix the bug in main.py"

# With GitHub access
moat codex --grant github

# Named run
moat codex --name my-feature

# Run in a git worktree (non-interactive with prompt)
moat codex --worktree=dark-mode --prompt "implement dark mode"

# Force rebuild
moat codex --rebuild

# Disable full-auto mode (require manual approval)
moat codex --full-auto=false
```

---

## moat gemini

Run Google Gemini CLI in a container.

```
moat gemini [workspace] [flags]
```

In addition to the command-specific flags below, `moat gemini` accepts all [common agent flags](#common-agent-flags).

### Arguments

| Argument | Description |
|----------|-------------|
| `workspace` | Workspace directory (default: current directory) |

### Command-specific flags

| Flag | Description |
|------|-------------|
| `-p`, `--prompt TEXT` | Run non-interactive with prompt |

Gemini does not have a `--noyolo` or `--full-auto` equivalent. The Gemini CLI does not expose a flag to skip confirmation prompts.

### Examples

```bash
# Interactive Gemini CLI
moat gemini

# In specific directory
moat gemini ./my-project

# Non-interactive with prompt
moat gemini -p "explain this codebase"
moat gemini -p "fix the bug in main.py"

# With GitHub access
moat gemini --grant github

# Named run
moat gemini --name my-feature

# Run in a git worktree (non-interactive with prompt)
moat gemini --worktree=dark-mode --prompt "implement dark mode"

# Force rebuild
moat gemini --rebuild
```

---

## moat wt

Create or reuse a git worktree for a branch and start a run in it.

```
moat wt <branch> [-- command]
```

The branch is created from HEAD if it doesn't exist. The worktree is created at `~/.moat/worktrees/<repo-id>/<branch>`.

Configuration is read from `moat.yaml` in the repository root. If a run is already active in the worktree, returns an error with instructions to stop it.

### Arguments

| Argument | Description |
|----------|-------------|
| `branch` | Branch name to create or reuse a worktree for |
| `command` | Command to run (overrides moat.yaml) |

### Flags

| Flag | Description |
|------|-------------|
| `-n`, `--name NAME` | Override auto-generated run name |
| `-g`, `--grant PROVIDER` | Inject credential (repeatable) |
| `-e KEY=VALUE` | Set environment variable (repeatable) |
| `--rebuild` | Force image rebuild |
| `--keep` | Keep container after completion |
| `--runtime` | Container runtime to use (`apple`, `docker`) |
| `--no-clipboard` | Disable host clipboard bridging for this run |
| `--no-sandbox` | Disable gVisor sandbox (Docker only) |
| `--tty-trace FILE` | Capture terminal I/O to file for debugging |

### Run naming

The run name is `{name}-{branch}` when `moat.yaml` has a `name` field, otherwise just `{branch}`.

### Worktree base path

Override the default worktree base path (`~/.moat/worktrees/`) with the `MOAT_WORKTREE_BASE` environment variable.

### Examples

```bash
# Start a run in a worktree for the dark-mode branch
moat wt dark-mode

# Run a specific command in the worktree
moat wt dark-mode -- make test

# List worktree-based runs
moat wt list

# Clean all stopped worktrees
moat wt clean

# Clean a specific worktree
moat wt clean dark-mode
```

### Subcommands

#### moat wt list

List worktree-based runs for the current repository. Equivalent to `moat list` filtered to worktree runs in the current repo.

```bash
moat wt list
```

#### moat wt clean

Remove worktree directories for stopped runs. Without arguments, cleans all stopped worktrees for the current repository. Never deletes branches.

`moat clean` also removes worktree directories as part of its broader cleanup. Use `moat wt clean` to target a specific branch or limit cleanup to worktrees.

```bash
moat wt clean [branch]
```

**Examples:**

```bash
# Clean all stopped worktrees for the current repo
moat wt clean

# Clean a specific worktree
moat wt clean dark-mode
```

---

## moat grant

Store credentials for injection into runs. See [Grants reference](/moat/reference/grants) for details on each provider, host matching rules, and credential sources.

```
moat grant <provider>[:<scopes>]
```

### Providers

| Provider | Description |
|----------|-------------|
| `github` | GitHub (gh CLI, env var, or PAT) |
| `claude` | Claude Code OAuth token |
| `anthropic` | Anthropic API key |
| `openai` | OpenAI (API key) |
| `gemini` | Google Gemini (Gemini CLI OAuth or API key) |
| `npm` | npm registries (.npmrc, `NPM_TOKEN`, or manual) |
| `aws` | AWS (IAM role assumption) |
| `oauth` | OAuth 2.0 (authorization code flow with PKCE) |

### moat grant github

GitHub credentials are obtained from multiple sources, in order of preference:

1. **gh CLI** -- Uses token from `gh auth token` if available
2. **Environment variable** -- Falls back to `GITHUB_TOKEN` or `GH_TOKEN`
3. **Personal Access Token** -- Interactive prompt for manual entry

```bash
moat grant github
```

### moat grant claude

Stores a Claude Code OAuth token. Presents a menu of OAuth token sources (setup-token, paste existing, or import from local Claude Code).

OAuth tokens are stored as `claude.enc`. See [Grants reference](./04-grants.md#anthropic--claude) for details.

```bash
moat grant claude
```

### moat grant anthropic

Stores an Anthropic API key. Reads from `ANTHROPIC_API_KEY` environment variable, or prompts interactively.

API keys are stored as `anthropic.enc`. Both credentials can coexist with `claude`.

```bash
moat grant anthropic
```

### moat grant openai

Stores an OpenAI API key. Reads from the `OPENAI_API_KEY` environment variable, or prompts interactively.

```bash
moat grant openai
```

### moat grant gemini

Stores a Google Gemini credential. Supports two authentication methods:

1. **Gemini CLI OAuth (recommended)** -- Imports OAuth tokens from your local Gemini CLI installation (`gemini`). Refresh tokens are stored for automatic access token renewal. If Gemini CLI credentials are detected, you are prompted to choose between OAuth import and API key.
2. **API key** -- Uses an API key from `aistudio.google.com/apikey`. Reads from `GEMINI_API_KEY` environment variable, or prompts interactively.

If no Gemini CLI credentials are found, falls directly to the API key prompt.

```bash
# Import from Gemini CLI or enter API key
moat grant gemini
```

### moat grant npm

Grant npm registry credentials. Auto-discovers registries from `~/.npmrc` and `NPM_TOKEN` environment variable.

```
moat grant npm [flags]
```

### Flags

| Flag | Description |
|------|-------------|
| `--host HOSTNAME` | Specific registry host (e.g., `npm.company.com`) |

### Examples

```bash
# Auto-discover registries from .npmrc
moat grant npm

# Add a specific registry
moat grant npm --host=npm.company.com
```

### moat grant mcp \<name\>

Store a credential for an MCP server.

```bash
moat grant mcp context7
```

The credential is stored as `mcp-<name>` (e.g., `mcp-context7`) and can be referenced in moat.yaml.

**Interactive prompts:**
- Credential (hidden input)

**Storage:**
- `~/.moat/credentials/mcp-<name>.enc`

### moat grant oauth

Grant OAuth credentials for a service. Acquires tokens via a browser-based authorization code flow with PKCE.

```
moat grant oauth <name> [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--url` | MCP server URL for OAuth discovery |
| `--auth-url` | OAuth authorization endpoint |
| `--token-url` | OAuth token endpoint |
| `--client-id` | OAuth client ID |
| `--client-secret` | OAuth client secret |
| `--scopes` | OAuth scopes (space-separated) |

Config resolution order: CLI flags, then `~/.moat/oauth/<name>.yaml`, then MCP discovery from `--url`.

#### Examples

```bash
# Auto-discover OAuth endpoints from an MCP server
moat grant oauth notion --url https://mcp.notion.com/mcp

# Provide endpoints directly
moat grant oauth linear \
    --auth-url https://linear.app/oauth/authorize \
    --token-url https://linear.app/api/oauth/token \
    --client-id your-client-id \
    --scopes "read write"
```

**Storage:**
- `~/.moat/credentials/oauth-<name>.enc`

### moat grant ssh

Grant SSH access to a specific host.

```
moat grant ssh --host <hostname>
```

### Flags

| Flag | Description |
|------|-------------|
| `--host HOSTNAME` | Host to grant access to (required) |

### Examples

```bash
moat grant ssh --host github.com
moat grant ssh --host gitlab.com
```

### moat grant aws

Grant AWS credentials via IAM role assumption.

```
moat grant aws --role=<ARN> [flags]
```

### Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--role ARN` | IAM role ARN to assume (required) | -- |
| `--region REGION` | AWS region for API calls | `us-east-1` |
| `--session-duration DURATION` | Session duration (e.g., `1h`, `30m`, `15m`) | `15m` |
| `--external-id ID` | External ID for cross-account role assumption | -- |
| `--aws-profile PROFILE` | AWS shared config profile for role assumption (falls back to `AWS_PROFILE` env var) | -- |

### Examples

```bash
# Basic role assumption
moat grant aws --role arn:aws:iam::123456789012:role/AgentRole

# With explicit region
moat grant aws --role arn:aws:iam::123456789012:role/AgentRole --region us-west-2

# With custom session duration
moat grant aws --role arn:aws:iam::123456789012:role/AgentRole --session-duration 2h

# Cross-account with external ID
moat grant aws --role arn:aws:iam::987654321098:role/CrossAccountRole --external-id abc123

# Full example
moat grant aws \
    --role arn:aws:iam::123456789012:role/AgentRole \
    --region eu-west-1 \
    --session-duration 30m
```

### moat grant list

List stored credentials. Shows credentials from the active profile, or the default store if no profile is set.

```
moat grant list
```

#### Examples

```bash
moat grant list
moat grant list --json
moat grant list --profile work
```

### moat grant show

Show details of a stored credential. Displays the provider, type, source, scopes, expiration, and a redacted token.

```
moat grant show <provider>
```

For SSH credentials, use `ssh:<host>` format.

#### Flags

| Flag | Description |
|------|-------------|
| `--show-token` | Reveal the full credential value (redacted by default) |

#### Examples

```bash
moat grant show github                    # Show GitHub credential details
moat grant show github --show-token       # Reveal the full token
moat grant show aws                       # Show AWS role configuration
moat grant show ssh:github.com            # Show SSH key details
moat grant show github --json             # Output as JSON
moat grant show github --profile myproj   # Show profile credential
```

#### Output fields

| Field | Description |
|-------|-------------|
| **Provider** | Provider name |
| **Type** | Credential type (token, oauth, api-key, role, key) |
| **Source** | How the credential was obtained (cli, env, pat, oauth) |
| **Scopes** | OAuth scopes, if applicable |
| **Granted** | When the credential was stored |
| **Expires** | Expiration time, or "never" |
| **Token** | Last 4 characters shown by default; full value with `--show-token` |

Provider-specific fields (AWS role ARN, region, session duration; SSH fingerprint and key path; npm registries) are shown when applicable.

### moat grant providers

List all available credential providers.

```bash
moat grant providers          # List all providers
moat grant providers --json   # Output as JSON
```

Output columns:

| Column | Description |
|--------|-------------|
| **PROVIDER** | Provider name (used with `moat grant <name>`) |
| **DESCRIPTION** | Brief description |
| **TYPE** | `builtin` or `custom` |

---

## moat revoke

Remove stored credentials. Operates on the active profile, or the default store if no profile is set.

```
moat revoke <provider>
```

### Examples

```bash
moat revoke github
moat revoke claude          # revokes OAuth token
moat revoke anthropic       # revokes API key
moat revoke npm
moat revoke ssh:github.com

# Revoke from a specific profile
moat revoke github --profile work
```

---

## moat logs

View container logs.

```
moat logs [flags] [run]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name (default: most recent) |

### Flags

| Flag | Description |
|------|-------------|
| `-n`, `--lines N` | Show last N lines (default: 100) |
| `-f`, `--follow` | Stream new log lines as they are written (exit with `Ctrl+C`) |

### Examples

```bash
# Most recent run
moat logs

# By name
moat logs my-agent

# By ID
moat logs run_a1b2c3d4e5f6

# Last 50 lines
moat logs -n 50

# Follow logs from a running container
moat logs -f my-agent

# Show last 20 lines, then follow
moat logs -n 20 -f my-agent
```

---

## moat trace

View execution traces and network requests.

```
moat trace [flags] [run]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name (default: most recent) |

### Flags

| Flag | Description |
|------|-------------|
| `--network` | Show network requests instead of spans |
| `-v`, `--verbose` | Show headers and bodies (requires `--network`) |

### Examples

```bash
# Execution spans
moat trace

# Network requests
moat trace --network

# Network with details
moat trace --network -v

# By name or ID
moat trace --network my-agent
moat trace --network run_a1b2c3d4e5f6
```

---

## moat audit

Verify audit log integrity.

```
moat audit [flags] <run>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name |

### Flags

| Flag | Description |
|------|-------------|
| `-e`, `--export FILE` | Export proof bundle |

### Examples

```bash
# Verify by name or ID
moat audit my-agent
moat audit run_a1b2c3d4e5f6

# Export proof bundle
moat audit run_a1b2c3d4e5f6 --export proof.json
```

---

### moat audit verify

Verify an exported proof bundle.

```
moat audit verify <file>
```

### Examples

```bash
moat audit verify proof.json
```

---

## moat list

List all runs.

```
moat list
```

### Output columns

| Column | Description |
|--------|-------------|
| NAME | Run name |
| RUN ID | Unique identifier |
| STATE | running, stopped, failed |
| AGE | Time since run was created |
| WORKTREE | Branch name (appears when any run has a worktree) |
| ENDPOINTS | Exposed services (from ports) |

The WORKTREE column appears when any run has a worktree branch. To show only worktree runs for the current repository, use `moat wt list`.

---

## moat status

Show high-level system status summary.

```
moat status
```

### Output sections

- **Runtime**: Docker or Apple containers
- **Active Runs**: Currently running containers with age, disk usage, and endpoints
- **Summary**: Counts and disk usage for stopped runs and cached images
- **Health**: Warnings about stopped runs and orphaned containers

For detailed information about all runs, use `moat list`.
For image details, use `moat system images`

---

## moat stop

Stop a running container.

```
moat stop [run]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name (default: most recent running) |

If a name matches multiple runs, you'll be prompted to confirm stopping all of them.

### Examples

```bash
# Stop most recent
moat stop

# Stop by name
moat stop my-agent

# Stop by ID
moat stop run_a1b2c3d4e5f6
```

---

## moat exec

Run a command inside a running container.

```
moat exec <run> -- <command> [args...]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name |
| `command` | Command and arguments to execute (after `--`) |

The exit code from the executed command is forwarded to the caller. If stdin is piped, it is forwarded to the command.

### Examples

```bash
# Run a command
moat exec run_a1b2c3d4e5f6 -- echo hello

# List workspace files
moat exec run_a1b2c3d4e5f6 -- ls /workspace

# Pipe data to a command
echo "data" | moat exec run_a1b2c3d4e5f6 -- cat

# Run a shell command
moat exec run_a1b2c3d4e5f6 -- sh -c "ps aux"
```

---

## moat destroy

Remove a stopped run and its artifacts.

```
moat destroy [run]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `run` | Run ID or name (default: most recent stopped) |

If a name matches multiple runs, you'll be prompted to confirm destroying all of them.

### Examples

```bash
# Destroy by name
moat destroy my-agent

# Destroy by ID
moat destroy run_a1b2c3d4e5f6
```

---

## moat clean

Clean up stopped runs, unused images, and worktree directories.

```
moat clean [flags]
```

Removes stopped runs, unused moat images, orphaned networks, and worktree directories for stopped runs. Worktree cleanup requires running from inside a git repository.

### Flags

| Flag | Description |
|------|-------------|
| `-f`, `--force` | Skip confirmation prompt |
| `--dry-run` | Show what would be removed |

### Examples

```bash
# Interactive cleanup
moat clean

# Force cleanup
moat clean -f

# Preview cleanup
moat clean --dry-run
```

To clean a single branch's worktree, use `moat wt clean <branch>`.

---

## moat volumes

Manage persistent volumes.

Volumes store data at `~/.moat/volumes/<agent-name>/<volume-name>/` and persist across runs for the same agent name. They are created automatically when `moat.yaml` specifies a `volumes:` section.

### moat volumes ls

List managed volumes.

```
moat volumes ls
```

### moat volumes rm

Remove all volumes for an agent.

```
moat volumes rm <agent-name> [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `-f`, `--force` | Skip confirmation prompt |

#### Examples

```bash
moat volumes rm my-agent
moat volumes rm my-agent --force
```

### moat volumes prune

Remove all managed volumes.

```
moat volumes prune [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `-f`, `--force` | Skip confirmation prompt |

#### Examples

```bash
moat volumes prune
moat volumes prune --force
```

---

## moat snapshot

Create and manage workspace snapshots.

When called with a run argument, creates a manual snapshot. Use subcommands to list, prune, or restore snapshots. All snapshot commands accept a run ID or name.

```
moat snapshot <run> [flags]
```

### Flags

| Flag | Description |
|------|-------------|
| `--label TEXT` | Optional label for the snapshot |

### Examples

```bash
moat snapshot my-agent
moat snapshot run_a1b2c3d4e5f6
moat snapshot run_a1b2c3d4e5f6 --label "before refactor"
```

### moat snapshot list

List snapshots for a run.

```
moat snapshot list <run>
```

#### Examples

```bash
moat snapshot list my-agent
moat snapshot list run_a1b2c3d4e5f6 --json
```

### moat snapshot prune

Remove old snapshots, keeping the newest N. The pre-run snapshot is always preserved.

```
moat snapshot prune <run> [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--keep N` | Keep N most recent (default: 5) |
| `--dry-run` | Preview what would be deleted |

#### Examples

```bash
moat snapshot prune my-agent --keep 3
moat snapshot prune run_a1b2c3d4e5f6 --dry-run
```

### moat snapshot restore

Restore workspace from a snapshot. If no snapshot ID is given, restores the most recent. A safety snapshot is created before in-place restores.

```
moat snapshot restore <run> [snapshot-id] [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--to DIR` | Extract to a different directory instead of restoring in-place |

#### Examples

```bash
moat snapshot restore my-agent
moat snapshot restore run_a1b2c3d4e5f6 snap_abc123
moat snapshot restore run_a1b2c3d4e5f6 --to /tmp/recovery
```

---

## moat proxy

Manage the proxy daemon. The proxy daemon is a long-lived process that handles credential injection, MCP relay, and hostname routing for all runs. It starts automatically when you run `moat run` and shuts down after 5 minutes idle (no active runs).

When called without a subcommand, shows the current proxy status.

### moat proxy start

Start the proxy daemon in the foreground. The daemon serves both the credential-injecting proxy and the routing reverse proxy on a single port.

This is primarily useful for debugging. In normal use, the daemon auto-starts on `moat run`.

```
moat proxy start [flags]
```

### Flags

| Flag | Description |
|------|-------------|
| `-p`, `--port N` | Proxy listen port (default: 8080) |

### Examples

```bash
moat proxy start
moat proxy start --port 9000
```

### moat proxy stop

Send a shutdown request to the proxy daemon via its Unix socket (`~/.moat/proxy/daemon.sock`). The daemon drains active connections before exiting.

```
moat proxy stop
```

### moat proxy status

Show daemon status: PID, proxy port, uptime, active run count, and registered routes.

```
moat proxy status
```

---

## moat deps

Manage dependencies. See [Dependencies](/moat/reference/dependencies) for details on the dependency system.

### moat deps list

List available dependencies from the registry.

```
moat deps list [flags]
```

### Flags

| Flag | Description |
|------|-------------|
| `--type TYPE` | Filter by dependency type (runtime, npm, apt, github-binary, go-install, uv-tool, custom, meta) |

### moat deps info

Show detailed information about a dependency.

```
moat deps info <name>
```

### Examples

```bash
# List all dependencies
moat deps list

# List only runtimes
moat deps list --type runtime

# List npm packages
moat deps list --type npm

# Show details for node
moat deps info node

# Show details for a meta dependency
moat deps info go-extras
```

---

## moat system

Low-level system commands.

### moat system images

List moat-managed container images.

```
moat system images
```

### moat system containers

List moat containers.

```
moat system containers
```

### moat system clean-temp

Clean up orphaned temporary directories.

```
moat system clean-temp [flags]
```

Moat creates temporary directories in `/tmp` for AWS credentials, Claude configuration, and Codex configuration. These are normally cleaned up when a run completes, but may accumulate if moat crashes.

This command scans for and removes temporary directories matching these patterns:
- `moat-aws-*` - AWS credential helper directories
- `agentops-aws-*` - AWS credential helper directories (legacy)
- `moat-claude-staging-*` - Claude configuration staging directories
- `moat-codex-staging-*` - Codex configuration staging directories
- `moat-npm-*` - npm credential configuration directories

Only directories older than `--min-age` are removed.

#### Flags

| Flag | Description |
|------|-------------|
| `--min-age DURATION` | Minimum age of temp directories to clean (default: 1h) |
| `--dry-run` | Show what would be cleaned without removing anything |
| `-f`, `--force` | Skip confirmation prompt |

#### Examples

```bash
# Show orphaned temp directories (dry run)
moat system clean-temp --dry-run

# Clean directories older than 24 hours
moat system clean-temp --min-age=24h

# Clean with automatic confirmation
moat system clean-temp --force

# Clean directories older than 1 week
moat system clean-temp --min-age=168h
```

---

## moat doctor

Diagnostic information about the Moat environment.

```
moat doctor [flags]
```

Shows version, container runtime status, credential status, Claude Code configuration, and recent runs. All sensitive information is automatically redacted.

### Flags

| Flag | Description |
|------|-------------|
| `-v`, `--verbose` | Show verbose output including JWT claims |

### Examples

```bash
moat doctor
moat doctor --verbose
```

### Subcommands

#### moat doctor claude

Diagnose Claude Code authentication and configuration issues in moat containers.

```
moat doctor claude [flags]
```

Compares your host Claude Code configuration against what's available in moat containers to identify authentication problems. Checks host `~/.claude.json` fields, credential status (OAuth vs API key, expiration), and field mapping via the host config allowlist.

With `--test-container`, runs three progressive validation levels that short-circuit on failure:

1. **Direct API call** -- verifies the stored token is valid by calling the Anthropic API from the host
2. **Proxy injection** -- spins up a TLS-intercepting proxy and verifies it replaces placeholder credentials with real ones
3. **Container test** -- launches a real moat container for full end-to-end verification

If level 1 fails (bad token), levels 2 and 3 are skipped. If level 2 fails (proxy issue), level 3 is skipped. This tells you exactly which layer is broken.

**Flags:**

| Flag | Description |
|------|-------------|
| `--verbose` | Show full configuration diff and all checked fields |
| `--json` | Output results as JSON for scripting |
| `--test-container` | Run progressive token validation and container auth test (~$0.0001 per level) |

**Exit codes:**

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | Configuration issues detected |
| 2 | Token validation or container authentication test failed (`--test-container` only) |

**Examples:**

```bash
# Basic diagnostics
moat doctor claude

# Full field-level diff
moat doctor claude --verbose

# JSON output for scripting
moat doctor claude --json

# End-to-end container auth test
moat doctor claude --test-container

# Combine flags
moat doctor claude --test-container --verbose
```

---

## moat version

Print the version of moat.

```
moat version
```

---

## moat tty-trace

Capture and analyze terminal I/O for debugging TUI rendering issues.

Use the `--tty-trace` flag with `moat claude`, `moat run -i`, or `moat wt` to capture traces, then analyze them with `moat tty-trace analyze`.

### moat tty-trace analyze

Analyze a terminal I/O trace file.

```
moat tty-trace analyze <trace-file> [flags]
```

#### Flags

| Flag | Description |
|------|-------------|
| `--decode` | Decode and display all control sequences |
| `--find-clears` | Find screen clear operations |
| `--find-resize-issues` | Find potential resize timing issues |
| `--resize-window N` | Time window in ms for resize issue detection (default: 100) |

#### Examples

```bash
# Capture a trace during a Claude session
moat claude --tty-trace=session.json

# Decode all control sequences
moat tty-trace analyze session.json --decode

# Find resize timing issues
moat tty-trace analyze session.json --find-resize-issues
```

---
[← Moat documentation index](https://majorcontext.com/moat/llms.txt)