Skip to main content
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:
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:
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:
4

Share and collaborate

Generate a share URL with --share. Anyone with the link can view the session transcript in a browser:

​
Session management commands

​
List sessions

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:

​
Delete a session

Permanently removes the session and all its messages from the local database.

​
Run flags for session control

These flags are available on bolt run:

​
Exporting sessions

Export a session’s full transcript as 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:
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.
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:
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

2

Fork before the risky next step

The forked session ID is printed to the console. The original session is untouched.
3

Share the fork for review

The share URL is printed once the session goes idle.
4

Import on another machine