docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876)

* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference

The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.

- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
  canonical pure-Go build), removing the unreleased commands/flags and
  fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
  builds and caches a canonical pure-Go bd from that tag, fetching the tag
  first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
  resolve bd through the pin and ignore a supplied binary while pinned
  (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
  now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
  bd <= v1.1.0 emits and converts it to the generic form before its normal
  Mintlify transform (tested); removable once the pin reaches a release
  whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
  Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
  beads-docs skill §8 updated to match.

* lint: annotate gosec G705 false positive in the docsmint legacy bridge

Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
This commit is contained in:
Chris Sells 2026-07-17 18:03:28 -07:00 • committed by GitHub
commit d2f87d50de
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
118 changed files with 882 additions and 1056 deletions

View file

@ -190,6 +190,14 @@ style, nav), edit `tools/docsmint` and its tests. The drift gates
(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,
and the docs-autofix bot) fail or auto-fix any hand edit.
**The docs describe the pinned release, not main.** `docs/cli-docs.pin`
names the release tag the whole docs corpus targets; the pipeline builds bd
from that tag and validates against it, so a Go-source edit on main shows up
in the committed docs only after the pin is bumped (at release time,
followed by a regeneration). Hand-written pages follow the same policy:
document what the pinned release does, never main-only features. See
`engdocs/decisions/2026-07-17-docs-release-pin.md`.
## 9. Verify before you call it done
Run the gates in [references/verification.md](references/verification.md).

File diff suppressed because it is too large Load diff

12
docs/cli-docs.pin Normal file
View file

@ -0,0 +1,12 @@
# Pins the bd version that the generated CLI docs are produced from and
# validated against: docs/CLI_REFERENCE.md, docs/cli-reference/, and the
# CLI Reference pages array in docs/docs.json.
#
# The published docs site describes the latest *release*, not main's source,
# so the docs pipeline builds bd from this tag (CGO_ENABLED=0, pure Go —
# CI's canonical build) instead of the current checkout. Bump this tag as
# part of each release, then run ./scripts/generate-cli-docs.sh.
#
# Set to HEAD to track the current checkout's source instead (the pre-pin
# behavior).
v1.1.0

View file

@ -1,6 +1,6 @@
---
title: "bd admin"
description: "Administrative commands for database maintenance"
description: "Administrative commands for beads database maintenance."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -18,7 +18,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
automatically. Use these admin commands for targeted database operations.
```
bd admin [command]
bd admin [flags]
```
## bd admin cleanup

View file

@ -1,6 +1,6 @@
---
title: "bd ado"
description: "Azure DevOps integration commands"
description: "Commands for syncing issues between beads and Azure DevOps."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem)
```
bd ado [command]
bd ado [flags]
```
## bd ado projects

View file

@ -1,6 +1,6 @@
---
title: "bd assign"
description: "Assign an issue to someone"
description: "Assign an issue to someone."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,27 +1,22 @@
---
title: "bd audit"
description: "Record and label agent interactions (append-only JSONL)"
description: "Audit log entries are appended to .beads/interactions.jsonl."
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc audit`.
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
Audit log entries are appended to .beads/interactions.jsonl.
This optional JSONL sidecar is disabled by default. Enable it with:
bd config set audit.enabled true
Issue history is always recorded in the database and is visible with
bd history &lt;id&gt; --events. The JSONL sidecar is for explicit interaction capture:
Each line is one event. This file is intended to be versioned in git and used for:
- auditing ("why did the agent do that?")
- dataset generation (SFT/RL fine-tuning)
Entries are append-only. Labeling creates a new "label" entry that references a parent entry.
```
bd audit [command]
bd audit [flags]
```
## bd audit label

View file

@ -1,6 +1,6 @@
---
title: "bd backup"
description: "Back up your beads database"
description: "Back up your beads database for off-machine recovery."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -25,18 +25,8 @@ DoltHub is recommended for cloud backup:
bd backup init https://doltremoteapi.dolthub.com/&lt;user&gt;/&lt;repo&gt;
Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication.
Auto-backup default:
When backup.enabled is unset, auto-backup turns ON in embedded mode if a
git remote exists, and stays OFF in sql-server / shared-server mode. In
server mode many bd clients share one Dolt server, and each would register
a server-side backup remote under the same name pointing at its own local
dir and full-sync the whole database — a self-amplifying storm. To back up
a shared server, run 'bd backup' explicitly (or set backup.enabled=true and
coordinate destinations). 'bd config get backup.enabled' shows the effective
value and its source.
```
bd backup [command]
bd backup [flags]
```
## bd backup init

View file

@ -1,6 +1,6 @@
---
title: "bd batch"
description: "Run multiple write operations in a single database transaction"
description: "Run multiple write operations in a single database transaction."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd bootstrap"
description: "Non-destructive database setup for fresh clones and recovery"
description: "Bootstrap sets up the beads database without destroying existing data."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd branch"
description: "List or create branches"
description: "List all branches or create a new branch."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd children"
description: "List child beads of a parent"
description: "List all beads that are children of the specified parent bead."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd close"
description: "Close one or more issues"
description: "Close one or more issues."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd comment"
description: "Add a comment to an issue"
description: "Add a comment to an issue."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd comments"
description: "View or manage comments on an issue"
description: "View or manage comments on an issue."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -24,7 +24,6 @@ Examples:
```
bd comments [issue-id] [flags]
bd comments [command]
```
**Flags:**

View file

@ -1,6 +1,6 @@
---
title: "bd compact"
description: "Squash old Dolt commits to reduce history size"
description: "Squash Dolt commits older than N days into a single commit."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd completion"
description: "Generate the autocompletion script for the specified shell"
description: "Generate the autocompletion script for bd for the specified shell."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -12,7 +12,7 @@ See each sub-command's help for details on how to use the generated script.
```
bd completion [command]
bd completion [flags]
```
## bd completion bash
@ -28,11 +28,11 @@ To load completions in your current shell session:
To load completions for every new session, execute once:
#### Linux:
### Linux:
bd completion bash &gt; /etc/bash_completion.d/bd
#### macOS:
### macOS:
bd completion bash &gt; $(brew --prefix)/etc/bash_completion.d/bd
@ -111,11 +111,11 @@ To load completions in your current shell session:
To load completions for every new session, execute once:
#### Linux:
### Linux:
bd completion zsh &gt; "$&#123;fpath[1]&#125;/_bd"
#### macOS:
### macOS:
bd completion zsh &gt; $(brew --prefix)/share/zsh/site-functions/_bd

View file

@ -1,6 +1,6 @@
---
title: "bd config"
description: "Manage configuration settings"
description: "Manage configuration settings for external integrations and preferences."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,12 +17,8 @@ Common namespaces:
- jira.* Jira integration settings
- linear.* Linear integration settings
- github.* GitHub integration settings
- gitlab.* GitLab integration settings
- ado.* Azure DevOps integration settings
- notion.* Notion integration settings
- custom.* Custom integration settings
- status.* Issue status configuration
- claim.* Claim arbitration settings (pool-aware claiming)
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
@ -56,18 +52,6 @@ Custom Status States:
This enables issues to use statuses like 'awaiting_review' in addition to
the built-in statuses (open, in_progress, blocked, deferred, closed).
Claim Pools:
A dispatcher can pre-assign issues to a pool pseudo-assignee (e.g.
"fable-crew") and let any actor take them with --claim. List the pool
aliases in the claim.pools config key, comma-separated:
bd config set claim.pools "fable-crew,night-crew"
Issues assigned to a real actor (or to an alias not in the list) keep
their anti-steal protection. Pool takes carry the normal lease; note
that if a taker's lease expires, bd reclaim returns the issue to the
unassigned pool, not to the pool alias it was dispatched to.
Suppressing Doctor Warnings:
Suppress specific bd doctor warnings by check name slug:
bd config set doctor.suppress.pending-migrations true
@ -84,7 +68,6 @@ Examples:
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"
bd config set claim.pools "fable-crew,night-crew" # Pool aliases claimable by any actor
bd config set doctor.suppress.pending-migrations true
bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu)
bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init
@ -93,7 +76,7 @@ Examples:
bd config unset jira.url
```
bd config [command]
bd config [flags]
```
## bd config apply

View file

@ -1,6 +1,6 @@
---
title: "bd context"
description: "Show effective backend identity and repository context"
description: "Show the effective backend identity information including repository paths,"
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd cook"
description: "Compile a formula into a proto (ephemeral by default)"
description: "Cook transforms a .formula.json file into a proto."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd count"
description: "Count issues matching filters"
description: "Count issues matching the specified filters."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd create-form"
description: "Create a new issue using an interactive form"
description: "Create a new issue using an interactive terminal form."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -53,10 +53,9 @@ bd create [title] [flags]
--silent Output only the issue ID (for scripting)
--skills string Required skills for this issue
--spec-id string Link to specification document
-s, --status string Initial status
--stdin Read description from stdin (alias for --body-file -)
--title string Issue title (alternative to positional argument)
-t, --type string Issue type (bug|feature|task|epic|chore|decision|spike|story|milestone); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
-t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
--validate Validate description contains required sections for issue type
--waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
--waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")

View file

@ -1,6 +1,6 @@
---
title: "bd defer"
description: "Defer one or more issues for later"
description: "Defer issues to put them on ice for later."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd delete"
description: "Delete one or more issues and clean up references"
description: "Delete one or more issues and clean up all references to them."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd dep"
description: "Manage dependencies"
description: "Manage dependencies between issues."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -21,7 +21,6 @@ Examples:
```
bd dep [issue-id] [flags]
bd dep [command]
```
**Flags:**

View file

@ -1,6 +1,6 @@
---
title: "bd diff"
description: "Show changes between two commits or branches"
description: "Show the differences in issues between two commits or branches."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd doctor"
description: "Check and fix beads installation health (start here)"
description: "Sanity check the beads installation for the current directory or specified path."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd dolt"
description: "Configure Dolt database settings"
description: "Configure and manage Dolt database settings and server lifecycle."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -50,7 +50,7 @@ Examples:
bd dolt test
```
bd dolt [command]
bd dolt [flags]
```
## bd dolt clean-databases
@ -58,7 +58,7 @@ bd dolt [command]
Identify and drop leftover test and agent databases that accumulate
on the shared Dolt server from interrupted test runs and terminated agents.
Stale database prefixes: testdb_*, beads_test*, beads_pt*, beads_vr*, doctest_*, doctortest_*, benchdb_*
Stale database prefixes: testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t*
These waste server memory and can degrade performance under concurrent load.
Use --dry-run to see what would be dropped without actually dropping.
@ -169,7 +169,7 @@ Subcommands:
remove &lt;name&gt; Remove a remote
```
bd dolt remote [command]
bd dolt remote [flags]
```
### bd dolt remote add
@ -180,12 +180,6 @@ Add a Dolt remote
bd dolt remote add <name> <url> [flags]
```
**Flags:**
```
--allow-git-origin Allow adding a Dolt remote whose URL matches the git origin (proceed with a warning instead of aborting)
```
### bd dolt remote list
List configured Dolt remotes
@ -260,10 +254,10 @@ Show the status of the Dolt engine for the current project.
In embedded mode, reports that the Dolt engine runs in-process and shows
the on-disk data directory. For beads-managed (local) servers, displays
PID, port, and data directory from the local PID file. For externally-
managed servers — a shared server (dolt.shared-server: true), a remote
dolt_server_host, or a local server managed outside bd (dolt.auto-start:
false, e.g. an orchestrator-shared sql-server) — pings the configured
endpoint via SQL and reports reachability, server version, and database.
managed servers — either a remote dolt_server_host or a local server
managed outside bd (dolt.auto-start: false, e.g. an orchestrator-shared
sql-server) — pings the configured endpoint via SQL and reports
reachability, server version, and database.
```
bd dolt status [flags]

View file

@ -1,6 +1,6 @@
---
title: "bd duplicate"
description: "Mark an issue as a duplicate of another"
description: "Mark an issue as a duplicate of a canonical issue."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd duplicates"
description: "Find and optionally merge duplicate issues"
description: "Find issues with identical content (title, description, design, acceptance criteria)."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd edit"
description: "Edit an issue field in $EDITOR"
description: "Edit an issue field using your configured $EDITOR."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -10,7 +10,7 @@ Generated from `bd help --doc epic`.
Epic management commands
```
bd epic [command]
bd epic [flags]
```
## bd epic close-eligible

View file

@ -1,6 +1,6 @@
---
title: "bd export"
description: "Export issues to JSONL format"
description: "Export all issues to JSONL (newline-delimited JSON) format."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -39,11 +39,9 @@ bd export [flags]
**Flags:**
```
--all Include all records (infra, templates, gates, memories)
--exclude-owner stringArray Exclude issues created by this identity (repeatable; also reads export.exclude_owners config)
--include-infra Include infrastructure beads (agents, roles, messages)
--include-memories Include persistent memories (from 'bd remember') in the export
-o, --output string Output file path (default: stdout)
--scrub Exclude test/pollution records
--verbose Print filtered issue count when owners are excluded
--all Include all records (infra, templates, gates, memories)
--include-infra Include infrastructure beads (agents, roles, messages)
--include-memories Include persistent memories (from 'bd remember') in the export
-o, --output string Output file path (default: stdout)
--scrub Exclude test/pollution records
```

View file

@ -1,6 +1,6 @@
---
title: "bd federation"
description: "Manage peer-to-peer federation (requires CGO)"
description: "Federation commands require CGO and the Dolt storage backend."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd find-duplicates"
description: "Find semantically similar issues using text analysis or AI"
description: "Find issues that are semantically similar but not exact duplicates."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd flatten"
description: "Squash all Dolt history into a single commit"
description: "Nuclear option: squash ALL Dolt commit history into a single commit."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd forget"
description: "Remove a persistent memory"
description: "Remove a memory by its key."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd formula"
description: "Manage workflow formulas"
description: "Manage workflow formulas - the source layer for molecule templates."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -19,19 +19,11 @@ Search paths (in order):
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
docs/workflows/formulas.md # narrative reference
list List available formulas from all search paths
show Show formula details, steps, and composition rules
```
bd formula [command]
bd formula [flags]
```
## bd formula convert
@ -77,9 +69,6 @@ Search paths (in order of priority):
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
@ -96,30 +85,6 @@ bd formula list [flags]
--type string Filter by type (workflow, expansion, aspect, convoy)
```
## bd formula schema
Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).
```
bd formula schema [primitive] [flags]
```
**Aliases:** primitives
## bd formula show
Show detailed information about a formula.
@ -131,9 +96,6 @@ Displays:
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema &lt;primitive&gt;'.
Examples:
bd formula show shiny
bd formula show rule-of-five

View file

@ -1,6 +1,6 @@
---
title: "bd gate"
description: "Manage async coordination gates"
description: "Gates are async wait conditions that block workflow steps."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,11 +17,9 @@ Gate types:
timer - Expires after timeout (Phase 2)
gh:run - Waits for GitHub workflow (Phase 3)
gh:pr - Waits for PR merge (Phase 3)
bead - Waits for another bead to close (Phase 4)
bead - Waits for cross-rig bead to close (Phase 4)
For bead gates, await_id is a bead ID in this rig's database (e.g., "bd-abc123").
The historical cross-rig form &lt;rig&gt;:&lt;bead-id&gt; can no longer be evaluated
(multi-rig routing removed) and stays pending until resolved manually.
For bead gates, await_id format is &lt;rig&gt;:&lt;bead-id&gt; (e.g., "other-project:op-abc123").
Examples:
bd gate list # Show all open gates
@ -31,7 +29,7 @@ Examples:
bd gate resolve &lt;id&gt; # Close a gate manually
```
bd gate [command]
bd gate [flags]
```
## bd gate add-waiter
@ -163,16 +161,12 @@ bd gate discover [flags]
## bd gate list
List gate issues.
With no argument, lists all gate issues in the current beads database.
With an [issue-id] argument, lists ONLY the gates that block that issue
(its own dependency gates) — not every gate in the database.
List all gate issues in the current beads database.
By default, shows only open gates. Use --all to include closed gates.
```
bd gate list [issue-id] [flags]
bd gate list [flags]
```
**Flags:**

View file

@ -1,6 +1,6 @@
---
title: "bd gc"
description: "Garbage collect: decay old issues, compact Dolt commits, run Dolt GC"
description: "Full lifecycle garbage collection for standalone Beads databases."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd github"
description: "GitHub integration commands"
description: "Commands for syncing issues between beads and GitHub."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise)
```
bd github [command]
bd github [flags]
```
## bd github pull

View file

@ -1,6 +1,6 @@
---
title: "bd gitlab"
description: "GitLab integration commands"
description: "Commands for syncing issues between beads and GitLab."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode
```
bd gitlab [command]
bd gitlab [flags]
```
## bd gitlab projects

View file

@ -1,6 +1,6 @@
---
title: "bd graph"
description: "Display issue dependency graph"
description: "Display a visualization of an issue's dependency graph."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -13,7 +13,6 @@ For epics, shows all children and their dependencies.
For regular issues, shows the issue and its direct dependencies.
With --all, shows all open issues grouped by connected component.
With --open, filters to only open/actionable issues (compact layer format).
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
@ -21,7 +20,6 @@ Display formats:
--compact Tree format, one line per issue, more scannable
--dot Graphviz DOT format (pipe to dot -Tsvg &gt; graph.svg)
--html Self-contained interactive HTML with D3.js visualization
--open Open issues only, compact layers (LLM-friendly)
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
@ -37,12 +35,9 @@ Examples:
bd graph --dot issue-id | dot -Tpng &gt; graph.png # PNG via Graphviz
bd graph --html issue-id &gt; graph.html # Interactive browser view
bd graph --all --html &gt; all.html # All issues, interactive
bd graph --open issue-id # Open issues only, layered by blocking order
bd graph --all --open # All open issues, compact layers
```
bd graph [issue-id] [flags]
bd graph [command]
```
**Flags:**
@ -53,7 +48,6 @@ bd graph [command]
--compact Tree format, one line per issue, more scannable
--dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)
--html Output self-contained interactive HTML (redirect to file)
--open Show only open issues (filters out closed/deferred), forces compact layer format
```
## bd graph check

View file

@ -1,6 +1,6 @@
---
title: "bd history"
description: "Show version history for an issue"
description: "Show the complete version history of an issue, including all commits"
---
{/* AUTO-GENERATED: do not edit manually */}
@ -13,7 +13,6 @@ where the issue was modified.
Examples:
bd history bd-123 # Show all history for issue bd-123
bd history bd-123 --limit 5 # Show last 5 changes
bd history bd-123 --events # Show database audit events
```
bd history <id> [flags]
@ -22,6 +21,5 @@ bd history <id> [flags]
**Flags:**
```
--events Show database audit events instead of commit snapshots
--limit int Limit number of history entries (0 = all)
```

View file

@ -1,6 +1,6 @@
---
title: "bd hooks"
description: "Manage git hooks for beads integration"
description: "Install, uninstall, or list git hooks for beads integration."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -17,7 +17,7 @@ The hooks provide:
- prepare-commit-msg: Add agent identity trailers for forensics
```
bd hooks [command]
bd hooks [flags]
```
## bd hooks install

View file

@ -1,6 +1,6 @@
---
title: "bd human"
description: "Show essential commands for human users"
description: "Display a focused help menu showing only the most common commands."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -22,7 +22,6 @@ SUBCOMMANDS:
```
bd human [flags]
bd human [command]
```
## bd human dismiss

View file

@ -1,6 +1,6 @@
---
title: "bd import"
description: "Import issues from a JSONL file or stdin into the database"
description: "Import issues from a JSONL file (newline-delimited JSON) into the database."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -7,32 +7,12 @@ description: Generated reference for every bd command
Generated from `bd help --docs-root`.
This reference covers all 112 live top-level `bd` commands. Regenerate it with:
This reference covers all 108 live top-level `bd` commands. Regenerate it with:
```bash
./scripts/generate-cli-docs.sh
```
## Global Flags
These flags apply to all commands:
```
--actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)
--db string Database path (default: auto-discover .beads/*.db)
-C, --directory string Change to this directory before running the command (like git -C)
--dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
--global Use the global shared-server database (beads_global)
--ignore-schema-skew Proceed despite forward schema drift (some queries may fail)
--json Output in JSON format
--no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0)
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables Dolt auto-push
-v, --verbose Enable verbose/debug output
```
## Commands
- [`bd admin`](/cli-reference/admin)
@ -77,7 +57,6 @@ These flags apply to all commands:
- [`bd github`](/cli-reference/github)
- [`bd gitlab`](/cli-reference/gitlab)
- [`bd graph`](/cli-reference/graph)
- [`bd heartbeat`](/cli-reference/heartbeat)
- [`bd history`](/cli-reference/history)
- [`bd hooks`](/cli-reference/hooks)
- [`bd human`](/cli-reference/human)
@ -97,7 +76,6 @@ These flags apply to all commands:
- [`bd merge-slot`](/cli-reference/merge-slot)
- [`bd metrics`](/cli-reference/metrics)
- [`bd migrate`](/cli-reference/migrate)
- [`bd migrate-personal`](/cli-reference/migrate-personal)
- [`bd mol`](/cli-reference/mol)
- [`bd note`](/cli-reference/note)
- [`bd notion`](/cli-reference/notion)
@ -115,7 +93,6 @@ These flags apply to all commands:
- [`bd quickstart`](/cli-reference/quickstart)
- [`bd ready`](/cli-reference/ready)
- [`bd recall`](/cli-reference/recall)
- [`bd reclaim`](/cli-reference/reclaim)
- [`bd recompute-blocked`](/cli-reference/recompute-blocked)
- [`bd remember`](/cli-reference/remember)
- [`bd rename`](/cli-reference/rename)
@ -139,7 +116,6 @@ These flags apply to all commands:
- [`bd tag`](/cli-reference/tag)
- [`bd todo`](/cli-reference/todo)
- [`bd types`](/cli-reference/types)
- [`bd unclaim`](/cli-reference/unclaim)
- [`bd undefer`](/cli-reference/undefer)
- [`bd update`](/cli-reference/update)
- [`bd upgrade`](/cli-reference/upgrade)

View file

@ -1,6 +1,6 @@
---
title: "bd info"
description: "Show database information"
description: "Display information about the current database."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd init-safety"
description: "Explain bd init flag semantics and the destroy-token format"
description: "bd init flag safety contract."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -59,7 +59,7 @@ DESTROY-TOKEN (non-interactive only)
In interactive (TTY) mode you confirm via a typed prompt instead. The
token is not echoed by bd's runtime error messages — this is a
deliberate guard against pattern-matched one-liners (see
engdocs/adr/0002-init-safety-invariants.md).
docs/adr/0002-init-safety-invariants.md).
EXIT CODES
@ -71,7 +71,7 @@ EXIT CODES
RECOVERY
If you hit a refusal, see docs/recovery/init-safety.md for step-by-step recovery
If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery
playbooks for each exit code.

View file

@ -1,6 +1,6 @@
---
title: "bd init"
description: "Initialize bd in the current directory"
description: "Initialize bd in the current directory by creating a .beads/ directory"
---
{/* AUTO-GENERATED: do not edit manually */}
@ -8,11 +8,10 @@ description: "Initialize bd in the current directory"
Generated from `bd help --doc init`.
Initialize bd in the current directory by creating a .beads/ directory
and its storage (a Dolt database by default). Optionally specify a custom issue prefix.
and Dolt database. Optionally specify a custom issue prefix.
Dolt is the default backend and the only one with version control (history,
branching, sync). Select an alternative with --backend=&lt;postgres|mysql|sqlite&gt;;
see docs/architecture/storage-backends.md for the trade-offs and setup.
Dolt is the default (and only supported) storage backend. The legacy SQLite
backend has been removed. Use --backend=sqlite to see migration instructions.
Use --database to specify an existing server database name, overriding the
default prefix-based naming. This is useful when an external tool (e.g. an orchestrator)
@ -49,56 +48,46 @@ bd init [flags]
**Flags:**
```
--agents-file string Custom filename for agent instructions (default: AGENTS.md)
--agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference)
--agents-template string Path to custom AGENTS.md template (overrides embedded default)
--backend string Storage backend: dolt (default), postgres, mysql, or sqlite. See docs/architecture/storage-backends.md.
--contributor Run OSS contributor setup wizard
--database string Use existing server database name (overrides prefix-based naming)
--debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers.
--destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>')
--discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.
--external Server is externally managed (skip server startup); use with --shared-server or --server
--force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').
--from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement
--init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds)
--mysql-database string MySQL database for this workspace (with --backend=mysql; MySQL's isolation unit)
--mysql-url string MySQL server DSN (with --backend=mysql), e.g. user:pass@tcp(host:3306)/ . A password may be included for init but is never persisted; set BEADS_MYSQL_PASSWORD for later commands. Falls back to BEADS_MYSQL_URL.
--non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments)
--pg-schema string Postgres schema for this workspace's tables (with --backend=postgres; provides search_path isolation)
--pg-url string Postgres connection URL (with --backend=postgres). A password may be included for init but is never persisted; set BEADS_PG_PASSWORD for later commands. Falls back to BEADS_POSTGRES_URL.
-p, --prefix string Issue prefix (default: current directory name)
--proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/dolt
--proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected.
--proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path.
--proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s).
--proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set.
--proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected.
--proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only).
--proxied-server-external-tls-ca-cert-path string [EXPERIMENTAL] Absolute path to a CA certificate (PEM) used to verify the externally-managed dolt sql-server. Empty uses the system trust store. Relative paths are rejected.
--proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected.
--proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected.
--proxied-server-external-tls-server-name string [EXPERIMENTAL] Server name to verify in the external dolt sql-server's TLS certificate. Defaults to the external host. Required with a unix socket unless --proxied-server-external-tls-skip-verify is set.
--proxied-server-external-tls-skip-verify [EXPERIMENTAL] Skip TLS certificate verification for the external dolt sql-server. Insecure; testing only.
--proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk.
--proxied-server-idle-timeout duration [EXPERIMENTAL] Idle duration after which the proxy shuts down its loopback listener and backend (proxied-server mode only). Omit for the built-in default (30s); 0 keeps the proxy and backend alive indefinitely; a positive value sets the window.
--proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: <beadsDir>/dolt/server.log. Relative paths are rejected.
--proxied-server-port int [EXPERIMENTAL] Fixed TCP port for the proxy's loopback listener (proxied-server mode only). Default 0 = an OS-assigned free port. Startup fails if the port is already in use.
--proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: <beadsDir>/dolt. May not exist yet — bd will create it. Relative paths are rejected.
-q, --quiet Suppress output (quiet mode)
--reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.
--remote string Dolt remote URL to clone from and persist as sync.remote
--role string Set beads role without prompting: "maintainer" or "contributor"
--server Use external dolt sql-server instead of embedded engine
--server-host string Dolt server host (default: 127.0.0.1)
--server-port int Dolt server port (default: 3307)
--server-socket string Unix domain socket path (overrides host/port)
--server-user string Dolt server MySQL user (default: root)
--setup-exclude Configure .git/info/exclude to keep beads files local (for forks)
--shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/)
--skip-agents Skip AGENTS.md and Claude/Codex/Cursor setup generation
--skip-hooks Skip git hooks installation
--sqlite-path string SQLite database file (with --backend=sqlite; relative to the beads dir, default beads.db)
--stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking
--team Run team workflow setup wizard
--agents-file string Custom filename for agent instructions (default: AGENTS.md)
--agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference)
--agents-template string Path to custom AGENTS.md template (overrides embedded default)
--backend string Storage backend (default: dolt). --backend=sqlite prints deprecation notice.
--contributor Run OSS contributor setup wizard
--database string Use existing server database name (overrides prefix-based naming)
--debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers.
--destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>')
--discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.
--external Server is externally managed (skip server startup); use with --shared-server or --server
--force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').
--from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement
--init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds)
--non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments)
-p, --prefix string Issue prefix (default: current directory name)
--proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb
--proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected.
--proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path.
--proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s).
--proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set.
--proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected.
--proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only).
--proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected.
--proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected.
--proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk.
--proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: <beadsDir>/proxieddb/server.log. Relative paths are rejected.
--proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: <beadsDir>/proxieddb. May not exist yet — bd will create it. Relative paths are rejected.
-q, --quiet Suppress output (quiet mode)
--reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.
--remote string Dolt remote URL to clone from and persist as sync.remote
--role string Set beads role without prompting: "maintainer" or "contributor"
--server Use external dolt sql-server instead of embedded engine
--server-host string Dolt server host (default: 127.0.0.1)
--server-port int Dolt server port (default: 3307)
--server-socket string Unix domain socket path (overrides host/port)
--server-user string Dolt server MySQL user (default: root)
--setup-exclude Configure .git/info/exclude to keep beads files local (for forks)
--shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/)
--skip-agents Skip AGENTS.md and Claude/Codex setup generation
--skip-hooks Skip git hooks installation
--stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking
--team Run team workflow setup wizard
```

View file

@ -1,6 +1,6 @@
---
title: "bd jira"
description: "Jira integration commands"
description: "Synchronize issues between beads and Jira."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -31,7 +31,7 @@ Examples:
bd jira status # Show sync status
```
bd jira [command]
bd jira [flags]
```
## bd jira pull

View file

@ -1,6 +1,6 @@
---
title: "bd kv"
description: "Key-value store commands"
description: "Commands for working with the beads key-value store."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -19,7 +19,7 @@ Examples:
bd kv list # List all key-value pairs
```
bd kv [command]
bd kv [flags]
```
## bd kv clear

View file

@ -10,15 +10,15 @@ Generated from `bd help --doc label`.
Manage issue labels
```
bd label [command]
bd label [flags]
```
## bd label add
Add labels to issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label add bd-123 label1,label2
Add a label to one or more issues
```
bd label add [issue-id...] [label[,label...]] [flags]
bd label add [issue-id...] [label] [flags]
```
## bd label list
@ -47,8 +47,8 @@ bd label propagate [parent-id] [label] [flags]
## bd label remove
Remove labels from issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label remove bd-123 label1,label2
Remove a label from one or more issues
```
bd label remove [issue-id...] [label[,label...]] [flags]
bd label remove [issue-id...] [label] [flags]
```

View file

@ -1,6 +1,6 @@
---
title: "bd linear"
description: "Linear integration commands"
description: "Synchronize issues between beads and Linear."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -70,7 +70,7 @@ Examples:
bd linear status # Show sync status
```
bd linear [command]
bd linear [flags]
```
## bd linear pull
@ -151,18 +151,6 @@ Type Filtering (--push only):
--parent TICKET Only push this ticket and its descendants
--relations Import Linear relations as bd dependencies on pull
Persistent push-direction ID filters (workflow artifacts, sandbox beads, etc.):
bd config set linear.exclude_id_prefix "hw-mol-"
bd config set linear.exclude_id_patterns "-wisp-,sandbox-,scratch-"
exclude_id_prefix is a single case-sensitive prefix on the bead ID.
exclude_id_patterns is a comma-separated list of case-sensitive substrings
(matched anywhere in the ID). Both are combined as a union: a bead
matching either rule is skipped from push (no create, no update). Beads
with an existing external_ref that NOW match are silently skipped on
future syncs; the Linear-side issue persists — archive/delete it manually
if desired.
Conflict Resolution:
By default, newer timestamp wins. Override with:
--prefer-local Always prefer local beads version

View file

@ -1,6 +1,6 @@
---
title: "bd link"
description: "Link two issues with a dependency"
description: "Link two issues with a dependency."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd lint"
description: "Check issues for missing template sections"
description: "Check issues for missing recommended sections based on issue type."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -15,7 +15,7 @@ Section requirements by type:
bug: Steps to Reproduce, Acceptance Criteria
task: Acceptance Criteria
feature: Acceptance Criteria
epic: Success Criteria (or Acceptance Criteria)
epic: Success Criteria
chore: (none)
Examples:
@ -34,5 +34,5 @@ bd lint [issue-id...] [flags]
```
-s, --status string Filter by status (default: open, use 'all' for all)
-t, --type string Filter by issue type (bug, task, feature, epic, decision, spike, story, chore, milestone)
-t, --type string Filter by issue type (bug, task, feature, epic)
```

View file

@ -31,8 +31,6 @@ bd list [flags]
--empty-description Filter issues with empty or missing description
--exclude-label strings Exclude issues that have ANY of these labels
--exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic)
--external-contains string Filter by external ref substring (case-insensitive)
--external-ref string Filter by exact external_ref value
--flat Disable tree format and use legacy flat list output
--format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template
--has-metadata-key string Filter issues that have this metadata key set

View file

@ -1,6 +1,6 @@
---
title: "bd mail"
description: "Delegate to mail provider (e.g., gt mail)"
description: "Delegates mail operations to an external mail provider."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd memories"
description: "List or search persistent memories"
description: "List all memories, or search by keyword."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd merge-slot"
description: "Manage merge-slot gates for serialized conflict resolution"
description: "Merge-slot gates serialize conflict resolution in the merge queue."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -27,7 +27,7 @@ Examples:
bd merge-slot release # Release the slot
```
bd merge-slot [command]
bd merge-slot [flags]
```
## bd merge-slot acquire

View file

@ -1,6 +1,6 @@
---
title: "bd metrics"
description: "Show or change anonymous usage-metrics settings"
description: "Show whether anonymous usage metrics are on, see exactly what is sent, and"
---
{/* AUTO-GENERATED: do not edit manually */}
@ -22,7 +22,6 @@ any user-supplied text.
```
bd metrics [flags]
bd metrics [command]
```
## bd metrics example

View file

@ -1,6 +1,6 @@
---
title: "bd migrate"
description: "Database migration commands"
description: "Database migration and data transformation commands."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -12,125 +12,26 @@ Database migration and data transformation commands.
Without subcommand, checks and updates database metadata to current version.
Subcommands:
hooks Plan git hook migration to marker-managed format
issues Move issues between repositories
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
from-server-to-proxied-server [EXPERIMENTAL] Switch server mode to proxied-server mode
from-proxied-server-to-server [EXPERIMENTAL] Switch proxied-server mode to server mode
from-shared-server-to-proxied-server [EXPERIMENTAL] Switch shared-server mode to proxied-server mode
from-proxied-server-to-shared-server [EXPERIMENTAL] Switch proxied-server mode to shared-server mode
On a remote-backed database with pending schema migrations bd refuses to
migrate in place (#4259): migrating two clones independently forks the schema
so bd dolt pull can no longer merge — the break is silent and unrecoverable.
Use --force to confirm you are the single designated migrator, after which you
should publish the migrated schema with 'bd dolt push'. The env-var equivalent
BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use.
hooks Plan git hook migration to marker-managed format
issues Move issues between repositories
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
```
bd migrate [flags]
bd migrate [command]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--inspect Show migration plan and database state for AI agent analysis
--json Output migration statistics in JSON format
--update-repo-id Update repository ID (use after changing git remote)
--yes Auto-confirm prompts
```
## bd migrate from-proxied-server-to-server
Switch a repo from proxied-server mode to server mode (bd init --server).
Both modes root their dolt sql-server at the same .beads/dolt directory, so this
only rewrites .beads/metadata.json (dolt_mode) and removes the proxied-server
sidecar — no Dolt data is copied or moved. Stop the running proxy first with
'bd dolt stop'.
Note: dolt_mode lives in the committed metadata.json, so this change propagates
to clones on the next push.
```
bd migrate from-proxied-server-to-server [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
```
## bd migrate from-proxied-server-to-shared-server
Switch a repo from proxied-server mode back to shared-server mode.
Only applies to a proxied-server repo rooted at the shared dolt directory
(~/.beads/shared-server/dolt) — the reverse of from-shared-server-to-proxied-server.
This rewrites .beads/metadata.json (dolt_mode), re-enables dolt.shared-server, and
removes the proxied-server sidecar; no Dolt data is copied or moved. Stop the
running proxy first with 'bd dolt stop'.
```
bd migrate from-proxied-server-to-shared-server [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
```
## bd migrate from-server-to-proxied-server
Switch a repo from server mode (bd init --server) to proxied-server mode.
Both modes root their dolt sql-server at the same .beads/dolt directory, so this
only rewrites .beads/metadata.json (dolt_mode) and writes the proxied-server
sidecar — no Dolt data is copied or moved. Stop the running server first with
'bd dolt stop'.
Note: dolt_mode lives in the committed metadata.json, so this change propagates
to clones on the next push.
```
bd migrate from-server-to-proxied-server [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime
```
## bd migrate from-shared-server-to-proxied-server
Switch a repo from shared-server mode to proxied-server mode.
The proxied server is rooted at the shared dolt directory
(~/.beads/shared-server/dolt), so no Dolt data is copied or moved; this rewrites
.beads/metadata.json (dolt_mode), turns off dolt.shared-server for this repo, and
writes the proxied-server sidecar. Stop the running shared server first with
'bd dolt stop' — note that stops it for every project sharing it.
```
bd migrate from-shared-server-to-proxied-server [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime
```
## bd migrate hooks
Analyze git hook files and sidecar artifacts for migration to marker-managed format.
@ -221,8 +122,7 @@ bd migrate schema [flags]
**Flags:**
```
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--json Output in JSON format
--json Output in JSON format
```
## bd migrate sync

View file

@ -1,6 +1,6 @@
---
title: "bd mol"
description: "Molecule commands (work templates)"
description: "Manage molecules - work templates for agent workflows."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -31,7 +31,7 @@ Commands:
Use "bd formula list" to list available formulas.
```
bd mol [command]
bd mol [flags]
```
**Aliases:** protomolecule
@ -238,8 +238,7 @@ bd mol last-activity <molecule-id> [flags]
Pour a proto into a persistent mol - like pouring molten metal into a mold.
This is the chemistry-inspired command for creating PERSISTENT work from templates.
The resulting mol is stored as persistent beads in the issue database and
syncs like any other bead (bd dolt push / pull).
The resulting mol lives in .beads/ (permanent storage) and is synced with git.
Phase transition: Proto (solid) -&gt; pour -&gt; Mol (liquid)
@ -319,12 +318,6 @@ Examples:
bd mol ready --gated [flags]
```
**Flags:**
```
--gated Find molecules ready for gate-resume dispatch (always on for this subcommand)
```
## bd mol seed
Verify that a formula is accessible and can be cooked.
@ -492,7 +485,6 @@ Subcommands:
```
bd mol wisp [proto-id] [flags]
bd mol wisp [command]
```
**Flags:**

View file

@ -1,6 +1,6 @@
---
title: "bd note"
description: "Append a note to an issue"
description: "Append a note to an issue's notes field."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd notion"
description: "Notion integration commands"
description: "Commands for syncing issues between beads and Notion."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -10,7 +10,7 @@ Generated from `bd help --doc notion`.
Commands for syncing issues between beads and Notion.
```
bd notion [command]
bd notion [flags]
```
## bd notion connect

View file

@ -1,6 +1,6 @@
---
title: "bd onboard"
description: "Display minimal snippet for agent instructions file"
description: "Display a minimal snippet to add to your agent instructions file for bd integration."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd orphans"
description: "Identify orphaned issues (referenced in commits but still open)"
description: "Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd ping"
description: "Check database connectivity"
description: "Lightweight health check that confirms bd can reach its database."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd preflight"
description: "Show PR readiness checklist"
description: "Display a checklist of common pre-PR checks for contributors."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -32,7 +32,7 @@ bd preflight [flags]
```
--check Run checks automatically
--fix Auto-fix issues where possible (vendorHash, version sync)
--fix Auto-fix issues where possible (not yet implemented)
--json Output results as JSON
--skip-lint Skip lint check explicitly
```

View file

@ -1,6 +1,6 @@
---
title: "bd prime"
description: "Output AI-optimized workflow context"
description: "Output essential Beads workflow context in AI-optimized markdown format."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -20,28 +20,11 @@ Config options:
- no-git-ops: When true, outputs stealth mode (no git commands in session close protocol).
Set via: bd config set no-git-ops true
Useful when you want to control when commits happen manually.
- agent.profile: Explicit policy profile for git/commit authority wording
(conservative | minimal | team-maintainer; default conservative).
Set via: bd config set agent.profile team-maintainer
Or per-session: BD_AGENT_PROFILE=team-maintainer (env var takes precedence).
See docs/getting-started/ide-setup.md#policy-profiles for what each profile means.
Workflow customization:
- Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default workflow text. Persistent memories (from bd remember) are still appended so memory injection keeps working under a custom template.
- Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely.
- Use --export to dump the default content for customization.
- Use --memories-only for hook contexts that should inject only persistent memories; this returns only the memories section even when a custom PRIME.md is present.
- Use --no-memories to omit the persistent memories section (useful when the memories section is large and would dominate a context budget). --memories-only takes precedence if both are set.
Memory injection caps:
Large memory sets can exceed what a session-start hook host will ingest,
and hosts truncate silently. Cap what prime injects with --max-memories N
and/or --max-memory-chars N (or the prime.max-memories /
prime.max-memory-chars config keys; an explicit flag wins, and an explicit
0 forces unlimited). Caps apply at whole-memory boundaries, at least one
memory is always emitted, and a banner ahead of the entries reports how
many were elided and how to browse the rest with bd memories.
--max-memory-chars caps the total bytes of the injected memory entries;
the section header and elision banner are excluded from the budget.
- Use --memories-only for hook contexts that should inject only persistent memories.
```
bd prime [flags]
@ -50,13 +33,10 @@ bd prime [flags]
**Flags:**
```
--export Output default content (ignores PRIME.md override)
--full Force full CLI output (ignore MCP detection)
--hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex)
--max-memories int Cap injected persistent memories to N entries (0 = unlimited; falls back to the prime.max-memories config key)
--max-memory-chars int Cap the total bytes of injected memory entries, at whole-memory boundaries; section header and banner are not counted (0 = unlimited; falls back to the prime.max-memory-chars config key)
--mcp Force MCP mode (minimal output)
--memories-only Output only persistent memories for compact hook contexts
--no-memories Omit the persistent memories section (ignored when --memories-only is set, which wins)
--stealth Stealth mode (no git operations, flush only)
--export Output default content (ignores PRIME.md override)
--full Force full CLI output (ignore MCP detection)
--hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex)
--mcp Force MCP mode (minimal output)
--memories-only Output only persistent memories for compact hook contexts
--stealth Stealth mode (no git operations, flush only)
```

View file

@ -1,6 +1,6 @@
---
title: "bd priority"
description: "Set the priority of an issue"
description: "Set the priority of an issue."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd promote"
description: "Promote a wisp to a permanent bead"
description: "Promote a wisp (ephemeral issue) to a permanent bead."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd prune"
description: "Delete old closed beads to reclaim space and shrink exports"
description: "Permanently delete closed non-ephemeral beads and their associated data."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -20,12 +20,6 @@ Use `--pattern '*'` if you really do want to sweep everything closed.
Deletes: issues, dependencies, labels, events, and comments for matching beads.
Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads.
Also skips closed beads whose ID appears in the description, notes, or
comments of any open / in-progress bead. This protects ADR / decision /
verification trails that downstream beads still cite. Use
--ignore-references to override (e.g., when bulk-decommissioning a
retired label across the rig).
To delete closed ephemeral beads (wisps, transient molecules) use
`bd purge` instead.
@ -48,7 +42,6 @@ bd prune [flags]
```
--dry-run Preview what would be pruned with stats
-f, --force Actually prune (without this, shows preview)
--ignore-references Delete closed beads even when referenced by open beads (use with care; see --help for details)
--older-than string Only prune beads closed more than N ago (e.g., 30d, 2w, 60)
--pattern string Only prune beads matching ID glob pattern (e.g., 'gm-old-*')
```

View file

@ -1,6 +1,6 @@
---
title: "bd purge"
description: "Delete closed ephemeral beads to reclaim space"
description: "Permanently delete closed ephemeral beads and their associated data."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd q"
description: "Quick capture: create issue and output only ID"
description: "Quick capture creates an issue and outputs only the issue ID."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -14,7 +14,6 @@ Example:
bd q "Fix login bug" # Outputs: bd-a1b2
ISSUE=$(bd q "New feature") # Capture ID in variable
bd q "Task" | xargs bd show # Pipe to other commands
bd q "Subtask" --parent=bd-a1b2 # Hierarchical child (outputs: bd-a1b2.1)
```
bd q [title] [flags]
@ -24,7 +23,6 @@ bd q [title] [flags]
```
-l, --labels strings Labels
--parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
-p, --priority string Priority (0-4 or P0-P4) (default "2")
-t, --type string Issue type (default "task")
```

View file

@ -1,6 +1,6 @@
---
title: "bd query"
description: "Query issues using a simple query language"
description: "Query issues using a simple query language that supports compound filters,"
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd quickstart"
description: "Quick start guide for bd"
description: "Display a quick start guide showing common bd workflows and patterns."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd ready"
description: "Show ready work (open, no active blockers)"
description: "Show ready work (open issues with no active blockers)."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd recall"
description: "Retrieve a specific memory"
description: "Retrieve the full content of a memory by its key."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd recompute-blocked"
description: "Recompute is_blocked for all issues (repairs stale flags after a pull)"
description: "Recompute the denormalized is_blocked flag for every issue and wisp."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd remember"
description: "Store a persistent memory"
description: "Store a memory that persists across sessions and account rotations."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd rename-prefix"
description: "Rename the issue prefix for all issues in the database"
description: "Rename the issue prefix for all issues in the database."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd rename"
description: "Rename an issue ID"
description: "Rename an issue from one ID to another."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd reopen"
description: "Reopen one or more closed issues"
description: "Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd repo"
description: "Manage multiple repository configuration"
description: "Configure and manage multiple repository support for multi-repo hydration."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -28,7 +28,7 @@ Examples:
bd repo sync # Sync from all configured repos
```
bd repo [command]
bd repo [flags]
```
## bd repo add

View file

@ -1,6 +1,6 @@
---
title: "bd restore"
description: "Restore the pre-compaction content of a compacted issue"
description: "Restore the pre-compaction content of a compacted issue."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -10,7 +10,7 @@ Generated from `bd help --doc rules`.
Audit and compact Claude rules
```
bd rules [command]
bd rules [flags]
```
## bd rules audit

View file

@ -1,6 +1,6 @@
---
title: "bd search"
description: "Search issues by text query"
description: "Search issues across title and ID (excludes closed issues by default)."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd set-state"
description: "Set operational state (creates event + updates label)"
description: "Atomically set operational state on an issue."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd setup"
description: "Setup integration with AI editors"
description: "Setup integration files for AI editors and coding assistants."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -13,8 +13,7 @@ Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration (rules + agent hooks)
bd setup cursor --global # Install global Cursor hooks (~/.cursor/hooks.json)
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks
bd setup codex --global # Install global Codex skill + guidance + native hooks
bd setup copilot # Install Copilot CLI plugin + repository instructions
@ -38,7 +37,7 @@ bd setup [recipe] [flags]
```
--add string Add a custom recipe with given name
--check Check if integration is installed
--global Install globally (claude/codex/cursor/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, ~/.cursor/hooks.json, or ~/.mux/AGENTS.md)
--global Install globally (claude/codex/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md)
--list List all available recipes
-o, --output string Write template to custom path
--print Print the template to stdout

View file

@ -1,6 +1,6 @@
---
title: "bd ship"
description: "Publish a capability for cross-project dependencies"
description: "Ship a capability to satisfy cross-project dependencies."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd sql"
description: "Execute raw SQL against the beads database"
description: "Execute a raw SQL query against the underlying database (SQLite or Dolt)."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd stale"
description: "Show stale issues (not updated recently)"
description: "Show issues that haven't been updated recently and may need attention."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd state"
description: "Query the current value of a state dimension"
description: "Query the current value of a state dimension from an issue's labels."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -23,7 +23,6 @@ Examples:
```
bd state <issue-id> <dimension> [flags]
bd state [command]
```
## bd state list

View file

@ -1,6 +1,6 @@
---
title: "bd status"
description: "Show issue database overview and statistics"
description: "Show a quick snapshot of the issue database state and statistics."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd statuses"
description: "List valid issue statuses"
description: "List all valid issue statuses and their categories."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd supersede"
description: "Mark an issue as superseded by a newer one"
description: "Mark an issue as superseded by a newer version."
---
{/* AUTO-GENERATED: do not edit manually */}

View file

@ -1,6 +1,6 @@
---
title: "bd swarm"
description: "Swarm management for structured epics"
description: "Swarm management commands for coordinating parallel work on epics."
---
{/* AUTO-GENERATED: do not edit manually */}
@ -13,7 +13,7 @@ A swarm is a structured body of work defined by an epic and its children,
with dependencies forming a DAG (directed acyclic graph) of work.
```
bd swarm [command]
bd swarm [flags]
```
## bd swarm create

Some files were not shown because too many files have changed in this diff Show more