# 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-cli

First 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_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 22 commands. Run any of them with --help for flags.

Command	Description
bolt	Launch the interactive TUI
run	Run a non-interactive prompt
attach	Attach the TUI to a running server
session	Manage sessions (list, delete)
agent	List and create agents
providers	Manage LLM provider credentials (alias: auth)
models	List available models
mcp	Manage MCP servers (add, list, auth, logout, debug)
serve	Start the headless API server
web	Start the server and open the web UI
upgrade	Upgrade to the latest version
uninstall	Remove bolt
completion	Generate shell completions
export	Export session history (with optional --sanitize)
import	Import a session from a file or share URL
plugin	Install and manage plugins
github	GitHub Actions agent (install, run)
pr	Check out a GitHub PR into a local branch
stats	Show token usage and cost statistics
db	Query the local session database
debug	Troubleshooting tools (config, lsp, snapshots, and more)
acp	Agent Client Protocol server for editors (e.g. Zed)