# documentation
Docs
Everything you need to get Bolt running and configured. Short version: install it, run bolt in a project, start typing.
Installation
Bolt ships as a single global binary on npm. Use the shell installer on macOS and Linux, or the package manager you already have.
# npm (any platform)
$
npm i -g @bolt-builder/bolt-cli# shell installer (macOS / Linux)
$
curl -fsSL https://raw.githubusercontent.com/bolt-builder/bolt-cli/dev/install | bash# bun / pnpm / yarn
$
bun add -g @bolt-builder/bolt-cliFirst run
From any project directory. Bolt picks up your project context automatically.
$terminal
# Open the TUI in the current directory
bolt
# Run a prompt directly (non-interactive)
bolt run "explain this codebase"
# Attach to a running server (local or remote)
bolt attach
# Start a session with a specific agent
bolt run --agent ask "what does this project do?"Configuration
Configuration lives in .bolt/bolt.jsonc in your project root, created on first run. It's JSONC, so comments are fine.
$.bolt/bolt.jsonc
{
"$schema": "https://opencode.ai/config.json",
"provider": {
// Provider config goes here
},
}Schema: https://opencode.ai/config.json
Environment variables
| Variable | Description |
|---|---|
| BOLT_<CONFIG_KEY> | Override any config key (BOLT_MODEL, BOLT_THEME, ...), typo-checked |
| BOLT_PROFILE | Select a named config profile |
| BOLT_LOG_LEVEL | Log level: DEBUG, INFO, WARN, ERROR |
| BOLT_PRINT_LOGS | Print logs to stderr |
| BOLT_PURE | Run without external plugins |
| BOLT_SERVER_PASSWORD | Basic auth password for the server |
| BOLT_SERVER_USERNAME | Basic auth username for the server |
CLI reference
All 86 commands. Run any of them with --help for flags.
| Command | Description |
|---|---|
| completion | generate shell completion script (pass 'fish' for fish) |
| acp | start ACP (Agent Client Protocol) server |
| mcp | manage MCP (Model Context Protocol) servers |
| attach | attach to a running bolt server |
| run | run bolt with a message |
| ask | ask a one-shot question and print only the answer to stdout |
| arena | race agents on the same task in isolated worktrees and keep the best result |
| init | initialize bolt config, agents, and commands for a project |
| debug | debugging and troubleshooting tools |
| config | inspect and manage configuration |
| providers | manage AI providers and credentials [aliases: auth] |
| agent | manage agents |
| upgrade | upgrade bolt to the latest or a specific version [aliases: update] |
| uninstall | uninstall bolt and remove all related files |
| serve | starts a headless bolt server |
| daemon | keep a warm bolt server running so one-shot commands skip boot |
| warm | pre-load project context and prompt cache before you start typing |
| web | start bolt server and open web interface |
| models | list all available models |
| stats | show token usage and cost statistics |
| eval | run agent evaluation cases and grade the results |
| logs | print the agent log |
| map | draw a markdown + mermaid map of source directory dependencies |
| arch | detect imports that violate the declared module contract |
| migrate | generate a major-version upgrade playbook for a dependency |
| deps | report outdated, vulnerable, deprecated, and abandoned dependencies |
| diff-gate | review a diff from stdin and exit 1 when defects reach a severity threshold |
| owners | map directory ownership from git history and CODEOWNERS |
| hotspots | flag files with high churn and high complexity for refactoring |
| packages | map the monorepo package graph and its build order |
| api | diff the exported API surface against a git ref |
| index | build an incrementally updated whole-repo vector index and query it |
| dead | find unused exports ranked by deletion safety |
| dupes | find near-identical code blocks across the repo |
| exec | run a markdown playbook of steps non-interactively, stopping on the first failure |
| export | export session data as JSON, markdown, JSONL, or an HTML replay |
| import | import session data from JSON file or URL |
| github | manage GitHub agent |
| pr | fetch and checkout a GitHub PR branch, then run bolt |
| push | push a session to a bolt server on another machine |
| pull | pull a session from a bolt server on another machine |
| stack | split the current branch into an ordered stack of reviewable branches |
| commit | commit staged changes with a generated message |
| commitlint | lint commit messages against this repo's own conventions |
| port | port a fix onto other branches with cherry-pick |
| split | split a messy worktree into logical commits with the agent |
| review | review code changes with the code-review agent |
| blast | estimate the blast radius of pending changes |
| undo | roll back the last agent turn (files and conversation) |
| analyze | run lint, typecheck, and dead-code checks over the current diff before handoff |
| checkpoint | save and rewind named checkpoints |
| rebase | plan an interactive rebase with the agent and explain every decision |
| invariants | state invariants before a refactor and verify them after |
| resolve | resolve merge conflicts by intent with the agent |
| codemod | generate an ast-grep transform, preview the diff, and apply it with --apply |
| asserts | find tests with missing or weak assertions and suggest better ones |
| pipeline | run a plan, code, review agent pipeline on a task |
| refactor | refactor with a test-verified loop: change, run, verify, repeat until green |
| tighten | find loose types in changed code and propose stricter ones |
| learn | learn this repository's conventions into project memory |
| drift | flag READMEs and comments that the current diff just made stale |
| memory | inspect project memory |
| watch | rerun a command on every file change, optionally fixing failures with the agent |
| jobs | manage background jobs started with run --background |
| cron | schedule recurring agent chores (dependency bumps, triage, drafts) |
| flaky | detect flaky tests by rerunning a command, and quarantine offenders |
| proptest | generate property-based tests for the pure functions in a file |
| guard | generate a failing regression test from a bug description before fixing it |
| mutate | mutate a file and rerun the tests to prove they catch bugs |
| mux | run parallel bolt sessions in tmux split panes |
| bisect | find the commit that broke a command, show blame, and propose a fix |
| batch | run a queue of prompts sequentially or in parallel with a summary table |
| why | answer when and why a behavior changed, with commit evidence |
| bench | benchmark a command on this change and on the base ref, and flag regressions |
| figma | generate components from a Figma design node |
| pair | share a live session between two terminals |
| session | manage sessions [aliases: sessions] |
| resume | resume a session, with a fuzzy picker when no id is given |
| grep | full-text search across every session transcript on disk |
| tag | tag a session (alias of session tag) |
| fork | fork a session at any message and continue down a different path |
| submodules | report submodule drift and bring submodules in sync |
| worktree | create, list, and clean agent worktrees |
| plugin | install plugin and update config [aliases: plug] |
| db | database tools |
| alias | list aliases, show one, or set one with name="expansion" |