CLI reference

Every command, with its options and exit codes, as logbook <command> --help prints them. For the common jobs, start with CLI recipes.

logbook start

logbook [start] [--port <n>] [--no-open] [--interval <minutes>] [--no-sync]

Serve the UI on 127.0.0.1, open it in the browser and sync every few minutes until Ctrl+C. It is the default command: logbook with no command, or with only these options, starts it.

Option	Value	Default	Help
--port	<n>, 0 to 65535	7314	TCP port on 127.0.0.1; 0 lets the system pick a free one
--no-open			Do not open the page in the browser (for SSH sessions, headless machines and tests)
--interval	<minutes>, at least 1	5	Minutes between scheduled syncs
--no-sync			Serve the warehouse as it is: no first sync and no schedule; the Sync button still works

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 4 port in use, 6 newer warehouse

Examples

logbook

Start the host on the default port, sync, and open the page in the browser.

logbook start --no-open --port 7400

Serve on port 7400 without opening a browser, as over SSH.

logbook start --no-sync

Serve the warehouse as it is, with no first sync and no schedule.

logbook sync

logbook sync

Import every session of your agents' history that changed since the last sync, then rebuild the links between sessions.

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running, 10 partial failure

Examples

logbook sync

Import what changed in your agents' history since the last sync.

logbook sessions

logbook sessions [--harness <id|alias>] [--origin <interactive|scripted|subagent>] [--project <text>]
                 [--goal <goal>] [--outcome <outcome>] [--since <YYYY-MM-DD>] [--limit <n>]

List sessions, newest first. --goal keeps those that pursued it, as their first or second goal: build a feature, fix a bug, refactor, migrate or clean up, review, explore the codebase, research outside the codebase, debug or diagnose, plan or specify, verify behaviour, ship and operate, set up environment or session, project admin, writing, extract or transform data, harness test or probe, no task, other. --outcome keeps those that ended so: done, partly done, handed off, blocked, failed, abandoned, no task, unclear.

Option	Value	Default	Help
--harness	`<id	alias>`
--origin	<origin>		Only sessions started this way
--project	<text>		Only sessions of projects matching this text
--goal	<goal>		Only sessions that pursued this goal, first or second
--outcome	<outcome>		Only sessions that ended so
--since	<YYYY-MM-DD>		Only sessions started on or after this day
--limit	<n>, at least 1	30	At most this many

Values of --origin: interactive, scripted, subagent

Values of --goal: build a feature, fix a bug, refactor, migrate or clean up, review, explore the codebase, research outside the codebase, debug or diagnose, plan or specify, verify behaviour, ship and operate, set up environment or session, project admin, writing, extract or transform data, harness test or probe, no task, other

Values of --outcome: done, partly done, handed off, blocked, failed, abandoned, no task, unclear

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook sessions --project shop --limit 10

The ten newest sessions of projects matching shop.

logbook sessions --harness opencode --origin subagent

Only the child sessions OpenCode started.

logbook sessions --goal "fix a bug" --since 2026-09-01

Sessions that set out to fix a bug since September 1.

logbook search

logbook search <query> [--limit <n>]

Full-text search over prompts, replies, reasoning, and tool input and output (FTS5 syntax: words, "phrases", prefix*, AND, OR, NOT).

Option	Value	Default	Help
--limit	<n>, at least 1	30	At most this many

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook search "discount code"

Every prompt, reply and tool call that holds the phrase.

logbook search "invoice AND rounding" --limit 5

The five best matches that hold both words.

logbook tree

logbook tree <session> [--root]

A session and every subagent session it started. A <session> is a warehouse id (claude-code:<uuid>) or the id the harness shows.

Option	Value	Default	Help
--root			Start from the session at the top of its tree

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook tree claude-code:de30da7a-0000-4000-8000-000000000001

The session and every subagent session it started.

logbook tree opencode:ses_demo3 --root

The whole tree this OpenCode session belongs to, from its top.

logbook timeline

logbook timeline <session>

A session's prompts, replies and tool calls in order, with durations. A <session> is a warehouse id (claude-code:<uuid>) or the id the harness shows.

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook timeline claude-code:de30da7a-0000-4000-8000-000000000001

The prompts, replies and tool calls of the session in order, with their durations.

logbook report

logbook report [<name>] [--max-rows <n>]

A canned report, or every report in a topic (failures, performance, usage, sessions, interaction); all of them without a name or with all. Reports: tool-failures, errors, shell, tool-causes, repeats, interrupts, tools, slow, latency, turn-time, longest-turns, heavy, output, skills, commands, families, models, daily, calls, chains, work, goals, outcomes, context, links, recovery, reactions, replies.

Option	Value	Default	Help
--max-rows	<n>, at least 1	200	At most this many rows per table

Values of <name>: tool-failures, errors, shell, tool-causes, repeats, interrupts, tools, slow, latency, turn-time, longest-turns, heavy, output, skills, commands, families, models, daily, calls, chains, work, goals, outcomes, context, links, recovery, reactions, replies, failures, performance, usage, sessions, interaction, all

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook report

Every report.

logbook report failures

Every report of the failures topic.

logbook report shell --max-rows 20

The shell report, at most 20 rows per table.

logbook sql

logbook sql <query> [--max-rows <n>]

Read-only SQL over the warehouse.

logbook sql --help prints the tables too; Database schema lists them.

Option	Value	Default	Help
--max-rows	<n>, at least 1	200	At most this many rows per table

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook sql "SELECT project_dir, COUNT(*) FROM session GROUP BY project_dir"

How many sessions each project directory holds.

logbook labels update

logbook labels update [--model <model>]

Label whatever is new with your own Claude Code: every task, one after another, leaving a session's outcome and its last reply until the session has been quiet for an hour. A usage limit stops it; every batch finished before it is stored.

Option	Value	Default	Help
--model	<model>	claude-haiku-4-5	Claude model id for every task of this run (default claude-haiku-4-5; pass a full id, not an alias). On a fixed 100-prompt sample Haiku agreed with Sonnet on 62% of prompt acts and of reaction sets and missed most redirects and praise.

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running, 7 missing prerequisite, 8 usage limit

Examples

logbook labels update

Label everything new with the default model.

logbook labels update --model claude-sonnet-5-5

Label everything new with Sonnet instead.

logbook labels run

logbook labels run --task <task> [--model <model>] [--sample <n>] [--limit <n>]

Label every record of one task this model has not labelled yet, through your own Claude Code. Each batch is stored as it lands, so a stopped run resumes; a usage limit stops it. --sample labels a fixed sample, the same for every model, to compare models on.

Option	Value	Default	Help
--task	<task>, required		The label task
--model	<model>	claude-haiku-4-5	Claude model id for every task of this run (default claude-haiku-4-5; pass a full id, not an alias). On a fixed 100-prompt sample Haiku agreed with Sonnet on 62% of prompt acts and of reaction sets and missed most redirects and praise.
--sample	<n>, at least 1		Label a fixed sample of n records, the same for every model, to compare models on
--limit	<n>, at least 1		Label at most n records in this run

Values of --task: shell, tool-failure, session, outcome, prompt, reply

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running, 7 missing prerequisite, 8 usage limit

Examples

logbook labels run --task shell

Label the shell calls the default model has not labelled yet.

logbook labels run --task prompt --sample 100 --model claude-sonnet-5-5

Label a fixed sample of 100 prompts with Sonnet, to compare it with another model.

logbook labels plan

logbook labels plan [--model <model>]

Print, as one JSON object, what labelling would send now: each task, its records and the input they would take, without calling a model.

Option	Value	Default	Help
--model	<model>	claude-haiku-4-5	Claude model id for every task of this run (default claude-haiku-4-5; pass a full id, not an alias). On a fixed 100-prompt sample Haiku agreed with Sonnet on 62% of prompt acts and of reaction sets and missed most redirects and praise.

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 7 missing prerequisite

Examples

logbook labels plan

What labelling would send now, as one JSON object, without calling a model.

logbook labels preview

logbook labels preview --task <task> [--batches <n>]

Print a task's next batches exactly as labelling would send them, without calling a model.

Option	Value	Default	Help
--task	<task>, required		The label task
--batches	<n>, 1 to 10	1	How many batches to show

Values of --task: shell, tool-failure, session, outcome, prompt, reply

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook labels preview --task reply

The next batch of the reply task, exactly as labelling would send it.

logbook labels preview --task shell --batches 3

The next three batches of the shell task.

logbook labels compare

logbook labels compare --task <task> --first <labeller> --second <labeller>

How often two labellers (rules, or a model) agree, field by field.

Option	Value	Default	Help
--task	<task>, required		The label task
--first	<labeller>, required		A labeller: rules, or a model id
--second	<labeller>, required		A labeller: rules, or a model id

Values of --task: shell, tool-failure, session, outcome, prompt, reply

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse

Examples

logbook labels compare --task shell --first rules --second claude-haiku-4-5

How often the rules and Haiku agree on each shell field.

logbook labels compare --task prompt --first claude-haiku-4-5 --second claude-sonnet-5-5

How often Haiku and Sonnet agree on each prompt field.

logbook labels drop

logbook labels drop --task <task> --labeller <model>

Delete one model's labels of one task. A report reads each record's newest model label, so after a comparison drop the labeller you did not choose.

Option	Value	Default	Help
--task	<task>, required		The label task
--labeller	<model>, required		The model whose labels to delete

Values of --task: shell, tool-failure, session, outcome, prompt, reply

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running

Examples

logbook labels drop --task prompt --labeller claude-haiku-4-5

Delete Haiku's prompt labels after choosing Sonnet's.

logbook forget

logbook forget <session>... | --project <dir>

Remove sessions from the warehouse for good, by id or every session of a project directory, then compact it. A <session> is a warehouse id (claude-code:<uuid>) or the id the harness shows.

Option	Value	Default	Help
--project	<dir>		Forget every session of this project directory

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running

Examples

logbook forget opencode:ses_demo2

Remove one session for good.

logbook forget --project /home/example/work/billing

Remove every session of the billing project.

logbook compact

logbook compact

Give back the disk space syncs leave free inside the warehouse.

Writes: yes

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted, 6 newer warehouse, 3 already running, 9 updated while running

Examples

logbook compact

Give back the space syncs left free inside the warehouse.

logbook doctor

logbook doctor

Print what Log Book finds on this machine: where each agent keeps its data, the warehouse and the versions, to paste into a bug report.

Writes: no

Exit codes: 0 success, 1 failure, 2 usage error, 130 interrupted

Examples

logbook doctor

It holds no session, prompt or project name, so you can paste it into an issue as it is.