CLI reference

This page documents every command with its positional arguments and options. For the narrative behind each subsystem, follow the links to the CLI subsystem page and the feature pages.

Global options

Available on every command:

Flag	Value	Meaning
--json	—	Machine output with stable schemas (the agent contract).
--quiet	—	Minimal output.
--cwd <path>	path	Run as if invoked from this directory.
--yes	—	No prompts; accept defaults.
--actor <actor>	human:<username> or agent:<tool>[:<model>]	Attribution for the write.
-V, --version	—	Print the version (root command only).

Wherever a command takes a <ref>, it accepts a canonical ID (BTL-20260724-a8q6), a unique ID fragment, or a #ordinal from beetl list.

Core loop

See Lifecycle for the state machine and gates, and Session store for the on-disk layout.

beetl init

Create .beetl/ in this repo and write config.

Option	Value	Meaning
--format <format>	json | toml	Config file format to write.
--private	—	Shortcut for privacy mode local-only.
--privacy-mode <mode>	committed | private-split | local-only	Privacy mode for the store.
--global	—	Enable the global ~/.beetl layer.
--username <name>	name	Identity for the user-level config.
--agent-install	—	Install the beetl agent skill + hook into .claude/.
--save-dev	—	Add beetl to package.json devDependencies.

beetl adopt

Write a config into an existing .beetl/ that has none (legacy store adoption).

Option	Value	Default	Meaning
--format <format>	json | toml	json	Config file format.

beetl new

File a new bug session (interactive for humans, one-shot JSON for agents).

Option	Value	Meaning
--title <text>	text	Session title.
--type <type>	defect | issue | cleanup | code-smell | typo | incident | near-miss	Session type.
--category <name>	name	Defect-kind category.
--surface <path>	path	Where it lives.
--tags <csv>	comma-separated	Tags.
--severity <level>	blocker | high | medium | low	Severity.
--symptoms <text>	text	report.symptoms.
--stdin	—	Capture piped stdin as report.errorOutput.
--classify	—	Ask the configured agent runner to suggest type/category/surface.
--json-input <file>	file or -	Full draft as JSON from a file or stdin.

beetl list

List sessions.

Option	Value	Meaning
--status <status>	a status, or open | terminal	Filter by status (or the open/terminal groups).
--type <type>	type	Filter by session type.
--category <name>	name	Filter by category.
--surface <path>	path	Filter by surface.
--tag <tag>	tag	Filter by tag.
--since <iso-date>	ISO date	Only sessions on/after this date.
--author <actor>	human:name, agent:tool[:model], or the name part	Filter by reporter.

beetl show <ref>

Show one session.

Argument	Required	Meaning
<ref>	yes	Session to display.

Option	Value	Meaning
--md	—	Render the markdown communication format.

beetl update <ref>

Update session fields (status changes go through move).

Argument	Required	Meaning
<ref>	yes	Session to update.

Option	Value	Meaning
--set <field=value...>	field=value (repeatable)	Dotted-path field assignment.
--json-input <file>	file or -	Object of field assignments as JSON.

beetl move <ref> <status>

Gated transition through the lifecycle.

Argument	Required	Values
<ref>	yes	Session to transition.
<status>	yes	reported | reproducing | diagnosing | fixing | verifying | resolved | wontfix | duplicate | cannot-reproduce

Option	Value	Meaning
--reason <text>	text	Reason (required for wontfix/duplicate/cannot-reproduce).
--symptoms <text>	text	report.symptoms.
--steps <text>	text	reproduction.steps.
--reliability <value>	always | intermittent | once | not-reproduced	reproduction.reliability.
--repro-reason <text>	text	reproduction.reason (required when not-reproduced).
--root-cause <text>	text	diagnosis.rootCause.
--mechanism <text>	text	diagnosis.mechanism.
--files <csv>	comma-separated	diagnosis.filesImplicated.
--fix-summary <text>	text	fix.summary.
--approach <value>	patch | refactor | revert | config | dependency	fix.approach.
--commits <csv>	comma-separated	fix.commits.
--tests <csv>	comma-separated	verification.testsAdded.
--no-test-reason <text>	text	verification.noTestReason (logged escape hatch).

beetl resolve <ref>

Move a session to resolved (chains through remaining gates). Takes the same field options as move (all except --reason): --symptoms, --steps, --reliability, --repro-reason, --root-cause, --mechanism, --files, --fix-summary, --approach, --commits, --tests, --no-test-reason — see the move table for values.

Argument	Required	Meaning
<ref>	yes	Session to resolve.

beetl close <ref>

Close a session as a terminal non-fix state.

Argument	Required	Meaning
<ref>	yes	Session to close.

Option	Value	Meaning
--as <status>	wontfix | duplicate | cannot-reproduce	Terminal state to close into.
--reason <text>	text	Stated reason (required for terminal states).

beetl file-complete

One-shot: create a session and walk every gate atomically (agent fast path). Always strict — loose mode does not apply here.

Option	Value	Default	Meaning
--json-input <file>	file or -	-	Full session record as JSON.

beetl checklist <ref>

Unmet gates for the next transition + missing high-value fields. No command-specific options.

Argument	Required	Meaning
<ref>	yes	Session to inspect.

Search & history

beetl search [query]

Lexical search over sessions.

Argument	Required	Meaning
[query]	no	Search terms.

Option	Value	Default	Meaning
--similar-to <ref>	ref	—	Find sessions similar to an existing one.
--limit <n>	number	10	Max hits.

beetl log

Failure-history view, oldest first.

Option	Value	Meaning
--module <path>	path	Filter by file/surface path prefix.
--author <who>	who	Filter by actor or attribution author (substring).
--refixes	—	Show refix lineage chains instead of the flat history.

beetl doctor

Validate the store: schemas, layout, duplicate IDs, broken links. Exits 2 when the store is unhealthy. No command-specific options.

beetl unlock <target>

Remove a crashed holder’s lock; refuses live owners.

Argument	Required	Values
<target>	yes	A session ref, or registry.

Option	Value	Meaning
--force	—	Unsafe: remove a lock whose owner liveness is unknown (foreign host / unreadable metadata).

Analysis

See Pattern engine and Attribution & blame.

beetl patterns

Authorless structural report: hotspots, heat map, refix chains, tempo.

Option	Value	Default	Meaning
--since <iso>	ISO date	—	Only sessions reported on/after this date.
--format <fmt>	md | json	md	Output format.
--no-cache	—	—	Recompute, ignoring .beetl/.cache/patterns/.
--synthesize	—	—	Cluster packs → LLM root-cause report.

beetl blame

Per-author/per-agent attribution analysis — local-only output by default.

Option	Value	Meaning
--author <who>	who	Filter authors/actors by substring.
--agents	—	Only sessions reported by agents.
--humans	—	Only sessions reported by humans.
--category <name>	name	Filter sessions by category.
--global	—	Analyze the ~/.beetl mirror across projects.
--record	—	Explicitly commit this report to .beetl/reports/.

Agents

See Agent integration.

beetl agent install

Write the beetl skill + auto-file hook into this project (.claude/).

Option	Value	Meaning
--claude-md	—	Also append a two-line pointer to CLAUDE.md.

beetl diagnose <ref>

Runner-driven diagnosis: walk the session toward diagnosing.

Argument	Required	Meaning
<ref>	yes	Session to diagnose.

Option	Value	Meaning
--runner <name>	claude | codex | api | none	Override the configured runner.
--dry-run	—	Print the exact prompt any runner would be asked.
--apply	—	Persist a metadata-only (api) candidate hypothesis as the session diagnosis.

Privacy, global layer, GitHub

See Privacy, Global layer, and GitHub Issues linking.

beetl privacy scan

Audit every session against current redaction patterns (no writes). No command-specific options.

beetl privacy redact <ref>

Rewrite one session applying current patterns (allowed on terminal sessions).

Argument	Required	Meaning
<ref>	yes	Session to rewrite.

beetl global enable / disable

Opt this project in/out of the ~/.beetl layer. enable takes no command-specific options.

beetl global disable:

Option	Value	Meaning
--keep-data	—	Keep the mirrored data in ~/.beetl instead of purging it.

beetl global sync / report / status / purge / repair

• sync — refresh this project’s mirror + registry entry.
• report — pattern engine across every mirrored project.
• status — this project’s global-layer state, including the last sync error.
• purge — remove this project’s mirror + registry entry from ~/.beetl (idempotent).
• repair — back up a corrupt registry and rebuild it from readable mirrors.

None take command-specific options.

beetl link <ref> [issue]

Link a session to a GitHub issue or related sessions.

Argument	Required	Values
<ref>	yes	Session to link.
[issue]	no	Issue number, #n, or URL.

Option	Value	Meaning
--create	—	Create a GitHub issue from the session via gh and link it.
--clear	—	Remove the GitHub issue link.
--related <refs...>	session refs	Record these refs as related sessions.