Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bolt-builder/bolt-cli/llms.txt

Use this file to discover all available pages before exploring further.

Most Bolt problems fall into a small number of categories. Work through the relevant accordion below, and check the log output with bolt logs whenever something unexpected happens.
For questions that aren’t answered here, search or start a discussion in the Bolt GitHub Discussions. Include the output of bolt debug info and bolt logs --tail 50 in your post so the community can help faster.
The bolt debug family of subcommands is your first stop for any mysterious behavior. Run bolt debug info for a one-shot system summary, bolt debug config to see the fully-resolved configuration, bolt debug paths to find where data is stored, and bolt debug snapshot to inspect session state.
Symptoms: The terminal flashes and exits immediately, or you see a stack trace before the TUI renders.Steps:
1

Collect system information

bolt debug info
This prints your Bolt version, OS, terminal emulator, and loaded plugins. Copy this output when reporting a bug.
2

Check recent log output

bolt logs --tail 100
Look for ERROR lines. A common cause is a plugin that fails to load — in that case you’ll see an error mentioning the plugin name.
3

Disable plugins to isolate the issue

bolt --pure
If Bolt starts cleanly with --pure, a plugin is causing the crash. Remove the offending plugin from your config, or report it to the plugin author.
4

Check for corrupted config

bolt debug config
If this prints an error about invalid JSON, open the config file it mentions and fix the syntax. Run bolt db path to confirm the database path is accessible.
Symptoms: Bolt shows “No providers configured”, API requests fail with 401 errors, or bolt run exits immediately without producing any output.Steps:
1

Re-run the provider login flow

bolt providers login
Select your provider and follow the prompts. Bolt will walk you through API key entry or OAuth.
2

Verify the API key environment variable

If you use an env var (e.g. ANTHROPIC_API_KEY), confirm it is actually set in the current shell:
echo $ANTHROPIC_API_KEY
If it is empty, add it to your shell profile and re-open your terminal.
3

Inspect the resolved config

bolt debug config
Look at the provider section. If your provider appears with a blank apiKey, the environment variable reference in your config file is not being expanded.
4

List stored credentials

bolt providers list
This shows all credentials stored in auth.json and all provider-related environment variables that Bolt detected.
Symptoms: bolt mcp list shows a server as failed or needs authentication, or the agent cannot use any tools from that server.Steps:
1

Run the MCP debug probe

bolt mcp debug <server-name>
This tests basic HTTP connectivity, inspects the WWW-Authenticate header, and walks through the OAuth discovery flow if applicable. The output will tell you whether the server is reachable and whether auth is required.
2

Check the server URL

Verify the URL in your .bolt/bolt.jsonc. For remote servers, make sure the URL ends with the MCP path (e.g. /mcp or /tools), not just the host.
3

Re-authenticate for OAuth servers

bolt mcp auth <server-name>
Follow the browser flow. If the server requires a pre-registered client ID, add it to the config:
"mcp": {
  "my-server": {
    "type": "remote",
    "url": "https://mcp.example.com/tools",
    "oauth": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }
}
4

Check local server command

For local servers, run the command manually in your terminal to confirm it starts without errors:
npx @modelcontextprotocol/server-filesystem /tmp
Symptoms: bolt run --session <id> exits with “Session not found”, or a session you remember working with has disappeared.Steps:
1

List all available sessions

bolt session list
Sessions are sorted by most-recently-updated first. If your session was deleted or the database was migrated, it will not appear here.
2

Find the database path

bolt db path
This prints the full path to the SQLite file. Verify the file exists and is not empty.
3

Query the database directly

bolt db "SELECT id, title FROM sessions ORDER BY time_updated DESC LIMIT 20"
If your session appears in the database but not in bolt session list, there may be a project ID mismatch — sessions are scoped to projects.
Symptoms: The agent asks for permission repeatedly, refuses to write files, or you see “Permission denied” banners.Understanding access levels:Each built-in agent has a declared access level that controls what it can do without asking:
Access levelWhat it allows
FullRead files, write files, run shell commands
EditRead and write files, no shell commands
ReadRead files only, no writes or commands
The code, debug, refactor, migrate, and perf agents have Full access. docs has Edit access. plan, ask, code-review, and security have Read access.Steps:
1

Switch to an agent with Full access

If you need file writes, use the code agent:
bolt run --agent code "implement the feature"
Or press Tab in the TUI to cycle through agents.
2

Use --auto to approve prompts non-interactively

In CI or scripted contexts, pass --auto to bolt run to auto-approve permissions that are not explicitly denied in the config.
3

Configure permissions in the config file

You can deny specific tools for all sessions in a project by adding a permission block to .bolt/bolt.jsonc.
Symptoms: bolt stats shows higher token counts than expected, or your API bill is growing faster than anticipated.Steps:
1

Review your usage statistics

bolt stats
bolt stats --days 7 --models
The output breaks down cost per day, average tokens per session, and usage by model.
2

Lower the reasoning effort

For models that support it, reduce the reasoning effort with --variant:
bolt run --model anthropic/claude-opus-4-5 --variant minimal "quick review"
Supported values are provider-specific (e.g. minimal, low, high, max).
3

Switch to a cheaper model

Use bolt models to find a smaller model. Smaller models (e.g. claude-haiku, gpt-4o-mini) cost significantly less per token and work well for many tasks.
4

Use the ask or plan agent for exploration

The ask and plan agents have Read access and do not invoke write tools, which means they avoid tool-heavy loops that generate large output tokens.
Symptoms: A slash-command behaves unexpectedly, the TUI renders incorrectly, or something changed after installing a plugin.Steps:
1

Disable all plugins to establish a baseline

bolt --pure
If the issue disappears, a plugin is responsible.
2

Identify the offending plugin

bolt debug info
The output lists all loaded plugins. Temporarily remove them one at a time from your config and restart Bolt until the issue is gone.
3

Check for version incompatibility

bolt upgrade
Plugins declare a compatible Bolt version range. If you recently upgraded Bolt, a plugin may need to be updated as well.
Symptoms: On Windows with WSL, Bolt cannot find less, file paths contain unexpected backslashes, or the pager for bolt session list does not launch.Steps:
1

Set the Git Bash path

Bolt looks for Unix utilities (including less) relative to the Git for Windows installation. Set the environment variable to your Git Bash directory:
$env:OPENCODE_GIT_BASH_PATH = "C:\Program Files\Git\bin"
Add this to your PowerShell profile ($PROFILE) to persist it.
2

Verify with debug info

bolt debug info
Confirms the OS detection and which paths Bolt is using.
3

Run Bolt inside WSL directly

For the best experience on Windows, run bolt from within a WSL terminal rather than from PowerShell or Command Prompt.
Symptoms: bolt upgrade reports an error or silently does nothing, or the version number does not change after running it.Steps:
1

Specify the installation method explicitly

Bolt tries to detect how it was installed. If detection fails, override it:
bolt upgrade --method npm
bolt upgrade --method curl
bolt upgrade --method brew
2

Reinstall via the install script

curl -fsSL https://raw.githubusercontent.com/bolt-builder/bolt-cli/dev/install | bash
3

Windows: run as Administrator for Chocolatey

If you installed via choco, upgrades require an elevated terminal. Open PowerShell as Administrator before running bolt upgrade.
4

Confirm the new version is active

bolt --version
which bolt    # verify the PATH is picking up the right binary
When filing an issue, the following information is most useful to maintainers:
1

Collect system and plugin info

bolt debug info
2

Collect recent log output

bolt logs --tail 200
3

Export the relevant session (sanitized)

If the problem happened during a specific session, export it with secrets redacted:
bolt export --sanitize > session-debug.json
Attach session-debug.json to the issue.
4

Open an issue or discussion

Go to GitHub Discussions and paste your bolt debug info output plus a description of the steps to reproduce.

Build docs developers (and LLMs) love

Get started for freeTalk to us