> ## Documentation Index
> Fetch the complete documentation index at: https://bolt-builder-bolt-cli-5b0aab46-mintlify-a8a84065.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bolt CLI command reference

> Complete reference for every Bolt CLI command, including flags, arguments, and usage examples for the TUI, run, serve, session, agent, and more.

Bolt exposes a single `bolt` binary with a rich set of subcommands. Running `bolt` with no arguments opens the full terminal UI. All other subcommands are listed below. Use `bolt <command> --help` at any time for inline help.

<Accordion title="bolt (default — launch TUI)">
  Opens the interactive terminal UI in the current directory. Bolt automatically discovers your project context, loads configuration, and connects to any configured providers.

  ```bash theme={null}
  bolt
  bolt --mini          # minimal split-footer interactive mode
  bolt --log-level DEBUG
  ```

  **Global flags** — available on every command:

  | Flag              | Type                             | Description                              |
  | ----------------- | -------------------------------- | ---------------------------------------- |
  | `--print-logs`    | boolean                          | Print log output to stderr               |
  | `--log-level`     | `DEBUG`\|`INFO`\|`WARN`\|`ERROR` | Set the log verbosity level              |
  | `--pure`          | boolean                          | Run without loading any external plugins |
  | `--help`, `-h`    | boolean                          | Show help text                           |
  | `--version`, `-v` | boolean                          | Print the installed version number       |
</Accordion>

<Accordion title="bolt run [prompt]">
  Run Bolt with a single prompt in non-interactive mode. Bolt starts an in-process server, sends the prompt to the active session, streams the response to stdout, then exits. Pipe stdin or pass `--file` to attach context.

  ```bash theme={null}
  # Basic non-interactive prompt
  bolt run "explain the auth module"

  # Continue the most recent session
  bolt run --continue "now add error handling"

  # Use a specific model with a specific agent
  bolt run --model anthropic/claude-opus-4-5 --agent code "refactor auth.ts"

  # Stream raw JSON events for tooling integration
  bolt run --format json "summarize changes"

  # Fire the same task at multiple models and keep the best result
  bolt run --best-of "anthropic/claude-opus-4-5,openai/gpt-4o" "write unit tests"

  # Attach a file as context
  bolt run --file ./openapi.yaml "generate a client SDK"

  # Attach to a remote server and run a prompt there
  bolt run --attach http://my-server:4096 --dir /projects/api "what tests are failing?"

  # Skip all permission prompts (dangerous)
  bolt run --auto "delete all TODO comments"
  ```

  | Flag                             | Alias | Type              | Description                                                                                       |
  | -------------------------------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------- |
  | `--command`                      |       | string            | Slash-command to execute; pass arguments as the message                                           |
  | `--continue`                     | `-c`  | boolean           | Continue the most recent session                                                                  |
  | `--session`                      | `-s`  | string            | Session ID to continue                                                                            |
  | `--fork`                         |       | boolean           | Fork the session before continuing (requires `--continue` or `--session`)                         |
  | `--share`                        |       | boolean           | Share the session after it completes                                                              |
  | `--model`                        | `-m`  | string            | Model to use in `provider/model` format                                                           |
  | `--best-of`                      |       | string            | Comma-separated `provider/model` list; runs the task in parallel, ranks results, keeps the winner |
  | `--agent`                        |       | string            | Agent to use (e.g. `code`, `ask`, `review`)                                                       |
  | `--format`                       |       | `default`\|`json` | Output format; `json` streams raw newline-delimited JSON events                                   |
  | `--file`                         | `-f`  | string\[]         | File(s) to attach as context                                                                      |
  | `--title`                        |       | string            | Title for the session                                                                             |
  | `--attach`                       |       | string            | Run against a remote Bolt server (e.g. `http://localhost:4096`)                                   |
  | `--password`                     | `-p`  | string            | Basic auth password for the remote server                                                         |
  | `--username`                     | `-u`  | string            | Basic auth username for the remote server                                                         |
  | `--dir`                          |       | string            | Working directory; if `--attach` is set, this is the directory on the remote server               |
  | `--port`                         |       | number            | Port for the local in-process server (random if omitted)                                          |
  | `--variant`                      |       | string            | Reasoning effort level, provider-specific (e.g. `high`, `max`, `minimal`)                         |
  | `--thinking`                     |       | boolean           | Show reasoning/thinking blocks in output                                                          |
  | `--mini`                         |       | boolean           | Start the minimal split-footer interactive UI (hidden)                                            |
  | `--interactive`                  | `-i`  | boolean           | Force direct interactive split-footer mode                                                        |
  | `--auto`                         |       | boolean           | Auto-approve permissions that are not explicitly denied                                           |
  | `--yolo`                         |       | boolean           | Skip all permission prompts (alias for `--auto`, hidden)                                          |
  | `--dangerously-skip-permissions` |       | boolean           | Skip all permission checks (hidden)                                                               |
  | `--demo`                         |       | boolean           | Enable direct interactive demo slash commands (hidden)                                            |
</Accordion>

<Accordion title="bolt arena [message..]">
  Race the same task across several agents in parallel, each isolated in its own git worktree, then have a judge model rank the results. Unlike `bolt run --best-of`, which shares one working directory and compares only answer text, arena contenders can freely edit files without stepping on each other. The judge sees each contender's final answer **plus its git diff**, so it ranks on what was actually built.

  Bolt writes the winning answer to stdout and sends the scoreboard, worktree paths, and progress notes to stderr. All worktrees are kept by default so you can inspect or merge the winning branch. Pass `--cleanup` to delete the losers' worktrees and branches after judging.

  ```bash theme={null}
  # Race Claude and GPT on the same task
  bolt arena --models anthropic/claude-sonnet-4,openai/gpt-5 \
    "add retry logic to the fetch helper"

  # Race the same model against itself (duplicates are allowed)
  bolt arena --models anthropic/claude-opus-4-5,anthropic/claude-opus-4-5 \
    "refactor the auth module"

  # Pick an explicit judge and clean up losing worktrees
  bolt arena --models "anthropic/claude-opus-4-5,openai/gpt-4o,google/gemini-2.5-pro" \
    --judge anthropic/claude-opus-4-5 --cleanup \
    "port this helper to TypeScript"

  # Machine-readable output
  bolt arena --models anthropic/claude-sonnet-4,openai/gpt-5 --format json \
    "write unit tests for parser.ts"
  ```

  | Flag        | Type              | Description                                                                                                   |
  | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
  | `--models`  | string            | **Required.** Comma-separated `provider/model` list (2+ entries, duplicates allowed) — one worktree per entry |
  | `--judge`   | string            | Judge model as `provider/model` (defaults to the first entry in `--models`)                                   |
  | `--agent`   | string            | Agent to use for every contender                                                                              |
  | `--variant` | string            | Model variant for contenders (provider-specific reasoning effort, e.g. `high`, `max`, `minimal`)              |
  | `--format`  | `default`\|`json` | Output format; `json` emits a single JSON result with the winner, ranking, and every candidate                |
  | `--cleanup` | boolean           | Remove losing worktrees and their branches after judging (default: `false`)                                   |

  <Note>
    Arena needs at least two `--models` entries and works inside a git repository. Bolt runs contenders with `question`, `plan_enter`, and `plan_exit` permissions denied, so agents cannot pause to ask for input mid-race.
  </Note>
</Accordion>

<Accordion title="bolt attach <url>">
  Attach the full TUI to a running Bolt server. The server can be local or remote. Pass `--mini` to use the minimal split-footer UI instead of the full TUI.

  ```bash theme={null}
  bolt attach http://localhost:4096
  bolt attach http://remote-host:4096 --dir /projects/api
  bolt attach http://remote-host:4096 --session abc123 --mini
  bolt attach http://remote-host:4096 --password secret --username alice
  ```

  | Flag             | Alias | Type    | Description                                                                   |
  | ---------------- | ----- | ------- | ----------------------------------------------------------------------------- |
  | `--dir`          |       | string  | Directory on the remote server                                                |
  | `--continue`     | `-c`  | boolean | Continue the most recent session on the remote server                         |
  | `--session`      | `-s`  | string  | Session ID to continue                                                        |
  | `--fork`         |       | boolean | Fork the session when continuing                                              |
  | `--password`     | `-p`  | string  | Basic auth password                                                           |
  | `--username`     | `-u`  | string  | Basic auth username                                                           |
  | `--mini`         |       | boolean | Use the minimal interactive UI                                                |
  | `--no-replay`    |       | boolean | Disable session history replay on resume and after resize (requires `--mini`) |
  | `--replay-limit` |       | number  | Cap visible replay to the newest N messages (requires `--mini`)               |
</Accordion>

<Accordion title="bolt serve">
  Start a headless Bolt API server. The server exposes a REST+SSE API that the TUI, `bolt run --attach`, and `bolt attach` can connect to. Bind on `0.0.0.0` to make it reachable from other machines — always set `BOLT_SERVER_PASSWORD` when doing so.

  ```bash theme={null}
  bolt serve
  bolt serve --hostname 0.0.0.0 --port 4096
  bolt serve --mdns
  ```

  | Flag            | Type      | Description                                                     |
  | --------------- | --------- | --------------------------------------------------------------- |
  | `--hostname`    | string    | Address to bind (default: `127.0.0.1`)                          |
  | `--port`        | number    | Port to listen on (random if omitted)                           |
  | `--mdns`        | boolean   | Enable mDNS service discovery (defaults hostname to `0.0.0.0`)  |
  | `--mdns-domain` | string    | Custom domain name for mDNS service (default: `opencode.local`) |
  | `--cors`        | string\[] | Additional domains to allow for CORS                            |

  <Warning>
    `BOLT_SERVER_PASSWORD` is not set by default. The server will log a warning and accept all connections until you set it.
  </Warning>
</Accordion>

<Accordion title="bolt web">
  Start the Bolt server and immediately open the web UI in your default browser. Accepts the same network flags as `bolt serve`.

  ```bash theme={null}
  bolt web
  bolt web --hostname 0.0.0.0 --port 4096
  bolt web --mdns
  ```

  | Flag            | Type      | Description                                                     |
  | --------------- | --------- | --------------------------------------------------------------- |
  | `--hostname`    | string    | Address to bind (default: `127.0.0.1`)                          |
  | `--port`        | number    | Port to listen on (random if omitted)                           |
  | `--mdns`        | boolean   | Enable mDNS service discovery (defaults hostname to `0.0.0.0`)  |
  | `--mdns-domain` | string    | Custom domain name for mDNS service (default: `opencode.local`) |
  | `--cors`        | string\[] | Additional domains to allow for CORS                            |
</Accordion>

<Accordion title="bolt session">
  Manage Bolt sessions stored in the local SQLite database.

  **Subcommands**

  ```bash theme={null}
  bolt session list                         # list all root sessions
  bolt session list --format json           # machine-readable output
  bolt session list -n 20                   # show 20 most recent sessions
  bolt session delete <sessionID>           # permanently delete a session
  ```

  **`bolt session list` flags**

  | Flag          | Alias | Type            | Description                                |
  | ------------- | ----- | --------------- | ------------------------------------------ |
  | `--max-count` | `-n`  | number          | Limit output to the N most recent sessions |
  | `--format`    |       | `table`\|`json` | Output format (default: `table`)           |
</Accordion>

<Accordion title="bolt agent">
  List and create custom agents. Agents are markdown files with YAML frontmatter that define a system prompt, permissions, and mode.

  ```bash theme={null}
  bolt agent list                           # list all available agents
  bolt agent create                         # interactive agent creation wizard

  # Non-interactive creation
  bolt agent create \
    --description "Audit code for security vulnerabilities" \
    --mode primary \
    --permissions "read,grep,glob" \
    --model anthropic/claude-opus-4-5 \
    --path .bolt/agents
  ```

  **`bolt agent create` flags**

  | Flag            | Alias     | Type                         | Description                                                  |
  | --------------- | --------- | ---------------------------- | ------------------------------------------------------------ |
  | `--path`        |           | string                       | Directory path to write the agent file                       |
  | `--description` |           | string                       | Natural language description of what the agent should do     |
  | `--mode`        |           | `all`\|`primary`\|`subagent` | Whether the agent acts as a primary agent, subagent, or both |
  | `--permissions` | `--tools` | string                       | Comma-separated list of allowed permissions (default: all)   |
  | `--model`       | `-m`      | string                       | Model to use in `provider/model` format                      |
</Accordion>

<Accordion title="bolt providers (alias: auth)">
  Interactively manage AI provider credentials. Credentials are stored in your OS data directory (`~/.local/share/bolt/auth.json` on Linux, `~/Library/Application Support/bolt/auth.json` on macOS).

  ```bash theme={null}
  bolt providers             # interactive credential management menu
  bolt auth                  # alias for bolt providers

  bolt providers list        # list stored credentials and active env vars
  bolt providers login       # add a credential for a provider
  bolt providers login --provider anthropic
  bolt providers login --provider anthropic --method "API Key"
  bolt providers logout      # remove a stored credential
  bolt providers logout --provider openai
  ```
</Accordion>

<Accordion title="bolt models [provider]">
  List all models available from your configured providers.

  ```bash theme={null}
  bolt models                         # list all models from all providers
  bolt models anthropic               # filter to a single provider
  bolt models --verbose               # include cost metadata in output
  bolt models --refresh               # force-refresh the models.dev cache
  ```

  | Flag        | Type    | Description                               |
  | ----------- | ------- | ----------------------------------------- |
  | `--verbose` | boolean | Include JSON cost metadata for each model |
  | `--refresh` | boolean | Refresh the models cache from models.dev  |
</Accordion>

<Accordion title="bolt mcp">
  Manage Model Context Protocol (MCP) servers. Bolt supports both remote (HTTP/SSE) servers with OAuth and local (stdio) servers.

  ```bash theme={null}
  bolt mcp add                              # interactive wizard to add a server
  bolt mcp add my-server --url https://mcp.example.com/tools
  bolt mcp add local-server -- npx @my-org/mcp-server
  bolt mcp list                             # show all configured servers and status
  bolt mcp auth <name>                      # run the OAuth flow for a server
  bolt mcp auth list                        # show OAuth status for all servers
  bolt mcp logout <name>                    # remove stored OAuth tokens
  bolt mcp debug <name>                     # probe connectivity and OAuth config
  ```

  **`bolt mcp add` flags**

  | Flag       | Type      | Description                                           |
  | ---------- | --------- | ----------------------------------------------------- |
  | `--url`    | string    | URL for a remote MCP server                           |
  | `--env`    | string\[] | Environment variable for a local server (`KEY=VALUE`) |
  | `--header` | string\[] | HTTP header for a remote server (`KEY=VALUE`)         |
</Accordion>

<Accordion title="bolt plugin install <module>">
  Install a Bolt plugin from npm and update the relevant config file. Plugins can extend the TUI, add new slash-commands, or register new providers.

  ```bash theme={null}
  bolt plugin install @my-org/bolt-plugin
  bolt plugin install @my-org/bolt-plugin --global      # install to global config
  bolt plugin install @my-org/bolt-plugin --force        # replace existing version
  ```

  | Flag       | Alias | Type    | Description                                                       |
  | ---------- | ----- | ------- | ----------------------------------------------------------------- |
  | `--global` | `-g`  | boolean | Add the plugin to the global config instead of the project config |
  | `--force`  | `-f`  | boolean | Replace an already-configured plugin version                      |
</Accordion>

<Accordion title="bolt github">
  Manage the Bolt GitHub Actions integration, which allows Bolt to respond to pull requests, issues, and other GitHub events.

  ```bash theme={null}
  bolt github install           # scaffold the GitHub Actions workflow in your repo
  bolt github run               # run the GitHub agent locally (for testing)
  bolt github run --event pull_request --token ghp_xxx
  ```

  **`bolt github run` flags**

  | Flag      | Type   | Description                                         |
  | --------- | ------ | --------------------------------------------------- |
  | `--event` | string | GitHub event name to simulate (e.g. `pull_request`) |
  | `--token` | string | GitHub personal access token                        |
</Accordion>

<Accordion title="bolt pr <number>">
  Check out a GitHub pull request as a local branch using the `gh` CLI, then launch Bolt in the checked-out directory. If the PR description contains a session share link, Bolt imports that session automatically.

  ```bash theme={null}
  bolt pr 123
  ```

  <Note>
    This command requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated.
  </Note>
</Accordion>

<Accordion title="bolt commit">
  Generate a commit message for staged (or all tracked) changes using an AI model and then commit. The model inspects recent commit history for style context.

  ```bash theme={null}
  bolt commit                        # commit staged changes
  bolt commit --all                  # stage and commit all tracked changes
  bolt commit --dry-run              # print the generated message without committing
  bolt commit --model openai/gpt-4o  # use a specific model
  ```

  | Flag        | Alias | Type    | Description                                      |
  | ----------- | ----- | ------- | ------------------------------------------------ |
  | `--all`     | `-a`  | boolean | Commit all tracked changes, not just staged ones |
  | `--dry-run` |       | boolean | Print the generated message without committing   |
  | `--model`   | `-m`  | string  | Model to use in `provider/model` format          |
</Accordion>

<Accordion title="bolt review">
  Run an AI code review on a diff and exit with code `0` (pass) or `1` (fail). The `code-review` agent examines the diff for correctness, style, and security issues, then emits a `Verdict: PASS` or `Verdict: FAIL` line.

  ```bash theme={null}
  bolt review                          # review uncommitted changes (git diff HEAD)
  bolt review --staged                 # review only staged changes
  bolt review --branch main            # review changes since merge base with main
  bolt review --model openai/o3        # use a specific model
  ```

  | Flag       | Alias | Type    | Description                                          |
  | ---------- | ----- | ------- | ---------------------------------------------------- |
  | `--staged` |       | boolean | Review staged changes only                           |
  | `--branch` |       | string  | Review changes since the merge base with this branch |
  | `--model`  | `-m`  | string  | Model to use in `provider/model` format              |

  <Note>
    Exit codes: `0` = PASS, `1` = FAIL, `2` = verdict could not be determined.
  </Note>
</Accordion>

<Accordion title="bolt export [sessionID]">
  Export a session as JSON to stdout. Useful for archiving, sharing, or feeding into other tools. Pass `--sanitize` before sharing publicly to redact file paths, prompts, and other sensitive transcript content.

  ```bash theme={null}
  bolt export                          # interactive session picker, then write to stdout
  bolt export abc123                   # export a specific session
  bolt export abc123 --sanitize        # redact secrets and paths
  bolt export abc123 > session.json    # write to a file
  ```

  | Flag         | Type    | Description                                                                |
  | ------------ | ------- | -------------------------------------------------------------------------- |
  | `--sanitize` | boolean | Redact sensitive data (file paths, prompt text, tool I/O) before exporting |
</Accordion>

<Accordion title="bolt import <file>">
  Import a previously exported session into the local database. Accepts either a local JSON file or a session share URL.

  ```bash theme={null}
  bolt import ./session.json
  bolt import https://opncd.ai/share/abc123
  ```
</Accordion>

<Accordion title="bolt stats">
  Display aggregate token usage and cost statistics across all sessions. Output includes an overview table, cost and token breakdown, model usage, and a tool usage bar chart.

  ```bash theme={null}
  bolt stats
  bolt stats --days 7             # last 7 days only
  bolt stats --models             # include per-model breakdown
  bolt stats --models 5           # show top 5 models
  bolt stats --tools 10           # show top 10 tools
  bolt stats --project ""         # filter to the current project only
  ```

  | Flag        | Type            | Description                                              |
  | ----------- | --------------- | -------------------------------------------------------- |
  | `--days`    | number          | Limit to the last N days (default: all time)             |
  | `--tools`   | number          | Number of tools to show in the tool usage chart          |
  | `--models`  | boolean\|number | Show model statistics; pass a number to cap the list     |
  | `--project` | string          | Filter by project ID; empty string means current project |
</Accordion>

<Accordion title="bolt logs">
  Print the Bolt application log. The log is stored at the OS log directory (e.g. `~/.local/state/bolt/opencode.log`).

  ```bash theme={null}
  bolt logs                        # print the last 1000 lines
  bolt logs --tail 200             # print the last 200 lines
  bolt logs --follow               # stream new lines as they are written
  bolt logs -f                     # alias for --follow
  ```

  | Flag       | Alias | Type    | Description                                       |
  | ---------- | ----- | ------- | ------------------------------------------------- |
  | `--tail`   |       | number  | Number of trailing lines to print (default: 1000) |
  | `--follow` | `-f`  | boolean | Stream new log lines in real time                 |
</Accordion>

<Accordion title="bolt db [query]">
  Query or inspect the local SQLite session database directly.

  ```bash theme={null}
  bolt db path                                  # print the database file path
  bolt db "SELECT id, title FROM sessions"      # run a SQL query (TSV output)
  bolt db "SELECT * FROM sessions" --format json
  ```

  | Flag       | Type          | Description                                      |
  | ---------- | ------------- | ------------------------------------------------ |
  | `--format` | `json`\|`tsv` | Output format for query results (default: `tsv`) |
</Accordion>

<Accordion title="bolt upgrade [target]">
  Upgrade Bolt to the latest release or a specific version. Bolt detects the installation method automatically and uses the appropriate package manager.

  ```bash theme={null}
  bolt upgrade                         # upgrade to the latest version
  bolt upgrade 0.2.0                   # upgrade (or downgrade) to a specific version
  bolt upgrade --method npm            # force a specific installation method
  bolt upgrade --method curl
  ```

  | Flag       | Alias | Type                                                   | Description                |
  | ---------- | ----- | ------------------------------------------------------ | -------------------------- |
  | `--method` | `-m`  | `curl`\|`npm`\|`pnpm`\|`bun`\|`brew`\|`choco`\|`scoop` | Installation method to use |
</Accordion>

<Accordion title="bolt uninstall">
  Remove the Bolt binary and all associated data.

  ```bash theme={null}
  bolt uninstall
  ```
</Accordion>

<Accordion title="bolt completion">
  Generate a shell completion script for `bash`, `zsh`, or `fish`.

  ```bash theme={null}
  bolt completion >> ~/.bashrc
  bolt completion >> ~/.zshrc
  ```
</Accordion>

<Accordion title="bolt debug">
  A collection of troubleshooting and introspection subcommands. Useful when filing bug reports or diagnosing unexpected behavior.

  ```bash theme={null}
  bolt debug info          # print version, OS, terminal, and loaded plugins
  bolt debug config        # print the fully-resolved configuration
  bolt debug paths         # print all global data/config/cache directories
  bolt debug lsp           # inspect LSP state
  bolt debug ripgrep       # test ripgrep availability
  bolt debug file          # inspect file tool behavior
  bolt debug scrap         # scratchpad for debugging
  bolt debug skill         # inspect available skills
  bolt debug snapshot      # inspect session snapshots
  bolt debug startup       # measure startup time
  bolt debug agents        # list agents and their resolved config
  bolt debug v2            # inspect V2 session core state
  bolt debug wait          # block indefinitely (for process debugging)
  ```
</Accordion>

<Accordion title="bolt acp">
  Start an ACP (Agent Client Protocol) server. ACP is the protocol used by editor integrations such as [Zed](https://zed.dev) to communicate with Bolt over stdin/stdout.

  ```bash theme={null}
  bolt acp
  bolt acp --cwd /path/to/project
  ```

  | Flag            | Type      | Description                                                     |
  | --------------- | --------- | --------------------------------------------------------------- |
  | `--cwd`         | string    | Working directory for the server (default: `process.cwd()`)     |
  | `--hostname`    | string    | Bind hostname (default: `127.0.0.1`)                            |
  | `--port`        | number    | Bind port                                                       |
  | `--mdns`        | boolean   | Enable mDNS service discovery                                   |
  | `--mdns-domain` | string    | Custom domain name for mDNS service (default: `opencode.local`) |
  | `--cors`        | string\[] | Additional domains to allow for CORS                            |
</Accordion>