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.

A session is Bolt’s primary unit of work. Every prompt you send, every file the agent reads or edits, and every tool call the model makes are durably recorded in that session’s history. Because sessions live in a local SQLite database, they survive process restarts, can be listed and queried at any time, and never leave your machine unless you explicitly share or export them.
All session data is stored locally in a SQLite database on your own machine. Nothing is sent to external servers unless you enable sharing. Use bolt db path to find the exact database file.

​
Session lifecycle

A session starts the moment you send your first prompt and ends only when you delete it. Between those two points you can freely detach, resume, branch, or hand it off.
1

Create or continue a session

Launch the TUI to start a new session interactively, or pass a prompt to bolt run to create one non-interactively:
# New session in the TUI
bolt

# New session non-interactively
bolt run "add error handling to the payment service"
2

Detach and come back later

Close the TUI at any time — the session is persisted automatically. Resume your most recent session with --continue, or target a specific session by ID with --session:
# Resume the most recent session
bolt run --continue "now write the tests too"

# Resume a specific session
bolt run --session ses_abc123 "continue from where we left off"
3

Fork before experimenting

Use --fork to branch from the current session history before trying a risky change. The fork is an independent session that does not affect the original:
bolt run --continue --fork "try rewriting this with a functional approach"
4

Share and collaborate

Generate a share URL with --share. Anyone with the link can view the session transcript in a browser:
bolt run --share --continue "final pass — clean up the diff"

​
Session management commands

​
List sessions

bolt session list
Outputs a formatted table of all sessions with their ID, title, and last-updated time. Add --format json to get machine-readable output, or -n <N> to limit to the most recent N sessions: 
bolt session list --format json
bolt session list -n 10

​
Delete a session

bolt session delete <sessionID>
Permanently removes the session and all its messages from the local database.

​
Run flags for session control

These flags are available on bolt run:
FlagAliasDescription
--continue-cContinue the most recent session
--session <id>-sContinue a specific session by ID
--forkFork the session before continuing (requires --continue or --session)
--shareGenerate a share URL for the session
--title <title>Set or override the session title

​
Exporting sessions

Export a session’s full transcript as JSON: 
# Export the most recent session
bolt export

# Export a specific session
bolt export <sessionID>

# Export with sensitive data redacted
bolt export --sanitize > transcript.json
The --sanitize flag replaces file paths, code content, tool inputs and outputs, and other potentially sensitive fields with [redacted:kind:id] placeholders — useful for sharing transcripts with teammates or filing bug reports.

​
Importing sessions

Import a session from a local JSON file or directly from a share URL: 
# From a local file
bolt import ./transcript.json

# From a share URL
bolt import https://opncd.ai/share/abc123
Imported sessions appear in your local session list and are fully resumable.

​
Querying the session database

Bolt exposes the underlying SQLite database directly for power users. 
# Print the database file path
bolt db path

# Open an interactive SQLite shell
bolt db

# Run an ad-hoc query
bolt db "SELECT id, title, time_updated FROM session ORDER BY time_updated DESC LIMIT 5"
Output format defaults to tab-separated values; add --format json for JSON output.

​
Token usage and cost statistics

bolt stats aggregates token usage and cost data across all your sessions: 
# All-time stats
bolt stats

# Last 7 days
bolt stats --days 7

# Current project only
bolt stats --project ""

# Show per-model breakdown (top 5 models)
bolt stats --models 5

# Limit tool-usage table to top 10 tools
bolt stats --tools 10
The output includes total sessions, messages, input/output/reasoning/cache tokens, total cost, average cost per day, average and median tokens per session, and a tool-usage breakdown. Pass --models to also show a per-model breakdown of messages, tokens, and cost.

​
Fork and share workflow

Here is a complete example of forking a session and sharing the result:
1

Start work in a new session

bolt run "refactor the UserService to use dependency injection"
2

Fork before the risky next step

bolt run --continue --fork "also migrate it to the new Repository pattern"
The forked session ID is printed to the console. The original session is untouched.
3

Share the fork for review

bolt run --session <forked-id> --share "final cleanup and comments"
The share URL is printed once the session goes idle.
4

Import on another machine

bolt import https://opncd.ai/share/<slug>

Build docs developers (and LLMs) love

Get started for freeTalk to us