docs(emitter): emit Mintlify CLI reference and generated docs.json nav

bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.

generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.

Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.

TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
This commit is contained in:
Chris Sells 2026-07-10 17:52:08 -07:00
commit 4ea6fa3ac0
120 changed files with 8223 additions and 29 deletions

View file

@ -182,6 +182,31 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth
fmt.Fprintf(w, "%s %s\n\n", heading, fullPath)
writeCommandBody(w, cmd)
// Subcommands
subCmds := cmd.Commands()
hasVisibleSubs := false
for _, sub := range subCmds {
if sub.IsAvailableCommand() {
hasVisibleSubs = true
break
}
}
if hasVisibleSubs {
for _, sub := range subCmds {
if !sub.IsAvailableCommand() {
continue
}
writeCommandHelp(w, sub, fullPath, depth+1)
}
}
}
// writeCommandBody writes the heading-independent parts of a command's help:
// description, usage, aliases, examples, and local flags.
func writeCommandBody(w io.Writer, cmd *cobra.Command) {
// Description
if cmd.Long != "" {
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Long))
@ -207,25 +232,6 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth
if localFlags.HasFlags() {
fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
}
// Subcommands
subCmds := cmd.Commands()
hasVisibleSubs := false
for _, sub := range subCmds {
if sub.IsAvailableCommand() {
hasVisibleSubs = true
break
}
}
if hasVisibleSubs {
for _, sub := range subCmds {
if !sub.IsAvailableCommand() {
continue
}
writeCommandHelp(w, sub, fullPath, depth+1)
}
}
}
// sidebarPositionMap maps command names to their Docusaurus sidebar position
@ -308,6 +314,25 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er
return err
}
if err := writeMintlifyCLIReferenceDir(filepath.Join(repoRoot, "docs", "cli-reference"), root); err != nil {
return err
}
// The Mintlify site's navigation lists every CLI page explicitly; those
// entries are generated here, never hand-maintained. Roots without a
// docs.json (bare output roots, --check scratch dirs before the copy)
// simply get the pages.
docsJSONPath := filepath.Join(repoRoot, "docs", "docs.json")
if _, err := os.Stat(docsJSONPath); err == nil {
navPages := []string{"cli-reference/index"}
for _, name := range availableCommandNames(root) {
navPages = append(navPages, "cli-reference/"+commandDocID(name))
}
if err := updateMintlifyCLINav(docsJSONPath, navPages); err != nil {
return err
}
}
if docsVersion != "" {
versionDir := filepath.Join(repoRoot, "website", "versioned_docs", "version-"+docsVersion, "cli-reference")
if err := writeCLIReferenceDir(versionDir, root, "v"+docsVersion); err != nil {
@ -318,6 +343,158 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er
return nil
}
// writeMintlifyCLIReferenceDir emits the Mintlify-form CLI reference under
// docs/cli-reference/: frontmatter title is the H1 (no body H1), links are
// root-relative and extensionless, and the auto-generated marker is a JSX
// comment because Mintlify parses .md through MDX (HTML comments break it).
func writeMintlifyCLIReferenceDir(outDir string, root *cobra.Command) error {
if err := os.MkdirAll(outDir, 0o755); err != nil {
return err
}
if err := removeMarkdownFiles(outDir); err != nil {
return err
}
commands := availableCommandNames(root)
if err := writeMarkdownFile(filepath.Join(outDir, "index.md"), mintlifyCLIReferenceIndex(commands)); err != nil {
return err
}
for _, name := range commands {
var out bytes.Buffer
if err := writeMintlifySingleCommandDoc(&out, root, name); err != nil {
return err
}
path := filepath.Join(outDir, commandDocID(name)+".md")
if err := writeMarkdownFile(path, out.String()); err != nil {
return err
}
}
return nil
}
// writeMintlifySingleCommandDoc renders one command as a Mintlify page. The
// frontmatter title renders as the page H1, so the top command emits its body
// without its own heading; subcommands start at ##.
func writeMintlifySingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error {
cmd := findCommand(root, cmdName)
if cmd == nil {
return fmt.Errorf("Error: command not found: %s", cmdName)
}
docCommand := strings.TrimSpace(strings.TrimPrefix(commandPath(cmd), root.Name()))
if docCommand == "" {
return errors.New("Error: cannot generate docs for root command")
}
fmt.Fprintf(w, "---\n")
fmt.Fprintf(w, "title: %q\n", "bd "+docCommand)
if cmd.Short != "" {
fmt.Fprintf(w, "description: %q\n", cmd.Short)
}
fmt.Fprintf(w, "---\n\n")
fmt.Fprintf(w, "{/* AUTO-GENERATED: do not edit manually */}\n\n")
fmt.Fprintf(w, "Generated from `bd help --doc %s`.\n\n", docCommand)
writeCommandBody(w, cmd)
fullPath := commandPath(cmd)
for _, sub := range cmd.Commands() {
if !sub.IsAvailableCommand() {
continue
}
writeCommandHelp(w, sub, fullPath, 2)
}
return nil
}
func mintlifyCLIReferenceIndex(commands []string) string {
var b strings.Builder
fmt.Fprintf(&b, "---\n")
fmt.Fprintf(&b, "title: CLI Reference\n")
fmt.Fprintf(&b, "description: Generated reference for every bd command\n")
fmt.Fprintf(&b, "---\n\n")
fmt.Fprintf(&b, "{/* AUTO-GENERATED: do not edit manually */}\n\n")
fmt.Fprintf(&b, "Generated from `bd help --docs-root`.\n\n")
fmt.Fprintf(&b, "This reference covers all %d live top-level `bd` commands. Regenerate it with:\n\n", len(commands))
fmt.Fprintf(&b, "```bash\n")
fmt.Fprintf(&b, "./scripts/generate-cli-docs.sh\n")
fmt.Fprintf(&b, "```\n\n")
fmt.Fprintf(&b, "## Commands\n\n")
for _, cmd := range commands {
fmt.Fprintf(&b, "- [`bd %s`](/cli-reference/%s)\n", cmd, commandDocID(cmd))
}
return b.String()
}
// updateMintlifyCLINav rewrites the "pages" array of the "CLI Reference"
// navigation group in docs.json, leaving every other byte of the file
// untouched. A textual splice (rather than a JSON round-trip) preserves key
// order and formatting so regeneration is diff-stable. The pages entries are
// plain slugs, so bracket matching cannot be confused by string contents.
func updateMintlifyCLINav(docsJSONPath string, pages []string) error {
data, err := os.ReadFile(docsJSONPath)
if err != nil {
return err
}
s := string(data)
groupIdx := strings.Index(s, `"group": "CLI Reference"`)
if groupIdx < 0 {
return fmt.Errorf("%s: no \"CLI Reference\" navigation group found", docsJSONPath)
}
pagesIdx := strings.Index(s[groupIdx:], `"pages"`)
if pagesIdx < 0 {
return fmt.Errorf("%s: \"CLI Reference\" group has no \"pages\" key", docsJSONPath)
}
pagesIdx += groupIdx
openIdx := strings.Index(s[pagesIdx:], "[")
if openIdx < 0 {
return fmt.Errorf("%s: \"CLI Reference\" pages key has no array", docsJSONPath)
}
openIdx += pagesIdx
depth := 0
closeIdx := -1
for i := openIdx; i < len(s); i++ {
switch s[i] {
case '[':
depth++
case ']':
depth--
if depth == 0 {
closeIdx = i
}
}
if closeIdx >= 0 {
break
}
}
if closeIdx < 0 {
return fmt.Errorf("%s: unbalanced \"pages\" array in \"CLI Reference\" group", docsJSONPath)
}
lineStart := strings.LastIndex(s[:pagesIdx], "\n") + 1
indent := s[lineStart:pagesIdx]
entryIndent := indent + " "
var b strings.Builder
b.WriteString("[\n")
for i, p := range pages {
fmt.Fprintf(&b, "%s%q", entryIndent, p)
if i < len(pages)-1 {
b.WriteString(",")
}
b.WriteString("\n")
}
b.WriteString(indent + "]")
out := s[:openIdx] + b.String() + s[closeIdx+1:]
// #nosec G306: docs.json is repository source, readable like other source files.
return os.WriteFile(docsJSONPath, []byte(out), 0o644)
}
func writeCLIReferenceDir(outDir string, root *cobra.Command, versionLabel string) error {
if err := os.MkdirAll(outDir, 0o755); err != nil {
return err

View file

@ -2,6 +2,7 @@ package main
import (
"bytes"
"encoding/json"
"os"
"path/filepath"
"strings"
@ -205,6 +206,171 @@ func TestWriteGeneratedCLIDocsDoesNotTouchVersionedDocsWithoutVersion(t *testing
assertFileContains(t, sentinel, "keep me")
}
func TestWriteGeneratedCLIDocsWritesMintlifyCLIReference(t *testing.T) {
root := &cobra.Command{Use: "bd"}
mol := testHelpCmd("mol", "Molecule commands")
mol.AddCommand(testHelpCmd("pour <formula>", "Start a workflow"))
root.AddCommand(
testHelpCmd("show <id>", "Show an issue"),
mol,
)
dir := t.TempDir()
if err := writeGeneratedCLIDocs(root, dir, ""); err != nil {
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
}
// Index page: Mintlify frontmatter, no body H1, extensionless links.
indexPath := filepath.Join(dir, "docs", "cli-reference", "index.md")
assertFileContains(t, indexPath, "title: CLI Reference")
assertFileContains(t, indexPath, "](/cli-reference/show)")
index, err := os.ReadFile(indexPath)
if err != nil {
t.Fatal(err)
}
for _, banned := range []string{"\n# ", "<!--", "sidebar_position", "](./"} {
if strings.Contains(string(index), banned) {
t.Errorf("Mintlify index.md contains banned %q:\n%s", banned, index)
}
}
// Command page: Mintlify frontmatter, no Docusaurus keys, JSX comment marker.
showPath := filepath.Join(dir, "docs", "cli-reference", "show.md")
assertFileContains(t, showPath, "title: \"bd show\"")
assertFileContains(t, showPath, "description: \"Show an issue\"")
assertFileContains(t, showPath, "{/* AUTO-GENERATED: do not edit manually */}")
assertFileContains(t, showPath, "bd show <id>")
show, err := os.ReadFile(showPath)
if err != nil {
t.Fatal(err)
}
for _, banned := range []string{"id: show", "slug:", "sidebar_position", "<!--", "\n# "} {
if strings.Contains(string(show), banned) {
t.Errorf("Mintlify show.md contains banned %q:\n%s", banned, show)
}
}
// Nested command page exists with the full command path.
molPath := filepath.Join(dir, "docs", "cli-reference", "mol.md")
assertFileContains(t, molPath, "## bd mol pour")
}
func TestUpdateMintlifyCLINavReplacesOnlyCLIReferencePages(t *testing.T) {
dir := t.TempDir()
docsJSON := filepath.Join(dir, "docs.json")
original := `{
"$schema": "https://mintlify.com/docs.json",
"name": "Beads Documentation",
"navigation": {
"groups": [
{
"group": "Getting Started",
"pages": [
"index",
"getting-started/installation"
]
},
{
"group": "CLI Reference",
"pages": [
"cli-reference/index",
"cli-reference/stale-command"
]
},
{
"group": "Reference",
"pages": [
"reference/faq"
]
}
]
}
}
`
if err := os.WriteFile(docsJSON, []byte(original), 0o644); err != nil {
t.Fatal(err)
}
if err := updateMintlifyCLINav(docsJSON, []string{"cli-reference/index", "cli-reference/create", "cli-reference/show"}); err != nil {
t.Fatalf("updateMintlifyCLINav() error = %v", err)
}
data, err := os.ReadFile(docsJSON)
if err != nil {
t.Fatal(err)
}
got := string(data)
for _, want := range []string{
`"cli-reference/create"`,
`"cli-reference/show"`,
`"getting-started/installation"`,
`"reference/faq"`,
} {
if !strings.Contains(got, want) {
t.Errorf("updated docs.json missing %q:\n%s", want, got)
}
}
if strings.Contains(got, "stale-command") {
t.Errorf("updated docs.json still lists stale CLI page:\n%s", got)
}
// The rewrite must remain valid JSON and preserve the other groups' pages.
var decoded map[string]any
if err := json.Unmarshal(data, &decoded); err != nil {
t.Fatalf("updated docs.json is not valid JSON: %v\n%s", err, got)
}
// Idempotent: running again must not change the file.
if err := updateMintlifyCLINav(docsJSON, []string{"cli-reference/index", "cli-reference/create", "cli-reference/show"}); err != nil {
t.Fatalf("updateMintlifyCLINav() second run error = %v", err)
}
again, err := os.ReadFile(docsJSON)
if err != nil {
t.Fatal(err)
}
if !bytes.Equal(data, again) {
t.Errorf("updateMintlifyCLINav is not idempotent:\nfirst:\n%s\nsecond:\n%s", data, again)
}
}
func TestWriteGeneratedCLIDocsUpdatesMintlifyNavWhenPresent(t *testing.T) {
root := &cobra.Command{Use: "bd"}
root.AddCommand(
testHelpCmd("show <id>", "Show an issue"),
testHelpCmd("create", "Create an issue"),
)
dir := t.TempDir()
docsDir := filepath.Join(dir, "docs")
if err := os.MkdirAll(docsDir, 0o755); err != nil {
t.Fatal(err)
}
docsJSON := filepath.Join(docsDir, "docs.json")
seed := `{
"navigation": {
"groups": [
{
"group": "CLI Reference",
"pages": [
"cli-reference/index"
]
}
]
}
}
`
if err := os.WriteFile(docsJSON, []byte(seed), 0o644); err != nil {
t.Fatal(err)
}
if err := writeGeneratedCLIDocs(root, dir, ""); err != nil {
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
}
assertFileContains(t, docsJSON, `"cli-reference/create"`)
assertFileContains(t, docsJSON, `"cli-reference/show"`)
}
func assertFileContains(t *testing.T, path, want string) {
t.Helper()
data, err := os.ReadFile(path)

158
docs/cli-reference/admin.md Normal file
View file

@ -0,0 +1,158 @@
---
title: "bd admin"
description: "Administrative commands for database maintenance"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc admin`.
Administrative commands for beads database maintenance.
These commands are for advanced users and should be used carefully:
cleanup Delete closed issues (issue lifecycle)
compact Compact old closed issues to save space (storage optimization)
reset Remove all beads data and configuration (full reset)
For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
automatically. Use these admin commands for targeted database operations.
```
bd admin [flags]
```
## bd admin cleanup
Delete closed issues to reduce database size.
This command permanently removes closed issues from the database.
NOTE: This command only manages issue lifecycle (closed -&gt; deleted). For general
health checks and automatic repairs, use 'bd doctor --fix' instead.
By default, deletes ALL closed issues. Use --older-than to only delete
issues closed before a certain date.
EXAMPLES:
bd admin cleanup --force # Delete all closed issues
bd admin cleanup --older-than 30 --force # Only issues closed 30+ days ago
bd admin cleanup --ephemeral --force # Only closed wisps (transient molecules)
bd admin cleanup --dry-run # Preview what would be deleted
SAFETY:
- Requires --force flag to actually delete (unless --dry-run)
- Supports --cascade to delete dependents
- Shows preview of what will be deleted
- Use --json for programmatic output
SEE ALSO:
bd doctor --fix Automatic health checks and repairs (recommended for routine maintenance)
bd admin compact Compact old closed issues to save space
```
bd admin cleanup [flags]
```
**Flags:**
```
--cascade Recursively delete all dependent issues
--dry-run Preview what would be deleted without making changes
--ephemeral Only delete closed wisps (transient molecules)
-f, --force Actually delete (without this flag, shows error)
--older-than int Only delete issues closed more than N days ago (0 = all closed issues)
```
## bd admin compact
Compact old closed issues using semantic summarization.
Compaction reduces database size by summarizing closed issues that are no longer
actively referenced. This is permanent graceful decay - original content is discarded.
Modes:
- Analyze: Export candidates for agent review (no API key needed)
- Apply: Accept agent-provided summary (no API key needed)
- Auto: AI-powered compaction (requires ANTHROPIC_API_KEY or ai.api_key, legacy)
- Dolt: Run Dolt garbage collection (for Dolt-backend repositories)
Tiers:
- Tier 1: Semantic compression (30 days closed, 70% reduction)
- Tier 2: Ultra compression (90 days closed) - planned, not yet implemented
Dolt Garbage Collection:
With auto-commit per mutation, Dolt commit history grows over time. Use
--dolt to run Dolt garbage collection and reclaim disk space.
--dolt: Run Dolt GC on .beads/dolt directory to free disk space.
This removes unreachable commits and compacts storage.
Examples:
# Dolt garbage collection
bd compact --dolt # Run Dolt GC
bd compact --dolt --dry-run # Preview without running GC
# Agent-driven workflow (recommended)
bd compact --analyze --json # Get candidates with full content
bd compact --apply --id bd-42 --summary summary.txt
bd compact --apply --id bd-42 --summary - &lt; summary.txt
# Legacy AI-powered workflow
bd compact --auto --dry-run # Preview candidates
bd compact --auto --all # Compact all eligible issues
bd compact --auto --id bd-42 # Compact specific issue
# Statistics
bd compact --stats # Show statistics
```
bd admin compact [flags]
```
**Flags:**
```
--actor string Actor name for audit trail (default "agent")
--all Process all candidates
--analyze Analyze mode: export candidates for agent review
--apply Apply mode: accept agent-provided summary
--auto Auto mode: AI-powered compaction (legacy)
--batch-size int Issues per batch (default 10)
--dolt Dolt mode: run Dolt garbage collection on .beads/dolt
--dry-run Preview without compacting
--force Force compact (bypass checks, requires --id)
--id string Compact specific issue
--json Output JSON format
--limit int Limit number of candidates (0 = no limit)
--stats Show compaction statistics
--summary string Path to summary file (use '-' for stdin)
--tier int Compaction tier (only tier 1 is implemented) (default 1)
--workers int Parallel workers (default 5)
```
## bd admin reset
Reset beads to an uninitialized state, removing all local data.
This command removes:
- The .beads directory (database, JSONL, config)
- Git hooks installed by bd
- Sync branch worktrees
By default, shows what would be deleted (dry-run mode).
Use --force to actually perform the reset.
Examples:
bd reset # Show what would be deleted
bd reset --force # Actually delete everything
```
bd admin reset [flags]
```
**Flags:**
```
--force Actually perform the reset (required)
```

115
docs/cli-reference/ado.md Normal file
View file

@ -0,0 +1,115 @@
---
title: "bd ado"
description: "Azure DevOps integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc ado`.
Commands for syncing issues between beads and Azure DevOps.
Configuration can be set via 'bd config' or environment variables:
ado.org / AZURE_DEVOPS_ORG - Organization name
ado.project / AZURE_DEVOPS_PROJECT - Project name (single)
ado.projects / AZURE_DEVOPS_PROJECTS - Project names (comma-separated)
ado.pat / AZURE_DEVOPS_PAT - Personal access token
ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem)
```
bd ado [flags]
```
## bd ado projects
List Azure DevOps projects that the configured token has access to.
```
bd ado projects [flags]
```
## bd ado pull
Pull one or more items from Azure DevOps.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd ado sync --pull-only --issues &lt;refs&gt;
```
bd ado pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
## bd ado push
Push one or more beads issues to Azure DevOps.
Accepts bead IDs as positional arguments.
Equivalent to: bd ado sync --push-only --issues &lt;ids&gt;
```
bd ado push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd ado status
Display current Azure DevOps configuration and sync status.
```
bd ado status [flags]
```
## bd ado sync
Synchronize issues between beads and Azure DevOps.
By default, performs bidirectional sync:
- Pulls new/updated work items from Azure DevOps to beads
- Pushes local beads issues to Azure DevOps
Use --pull-only or --push-only to limit direction.
Filters (--area-path, --iteration-path, --types, --states) restrict
which work items are synced. On pull, they limit the WIQL query. On push,
--types and --states filter local beads before pushing to ADO. Use
--no-create with push to skip creating new ADO work items (only update
existing linked items). Filters can also be persisted via config:
ado.filter.area_path, ado.filter.iteration_path,
ado.filter.types, ado.filter.states
CLI flags override config values when both are set.
```
bd ado sync [flags]
```
**Flags:**
```
--area-path string Filter to ADO area path (e.g., "Project\Team")
--bootstrap-match Enable heuristic matching for first sync
--dry-run Show what would be synced without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--iteration-path string Filter to ADO iteration path (e.g., "Project\Sprint 1")
--no-create Never create new items in either direction (pull or push)
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-ado On conflict, use Azure DevOps version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--project strings Project name(s) to sync (overrides configured project/projects)
--pull-only Only pull issues from Azure DevOps
--push-only Only push issues to Azure DevOps
--reconcile Force reconciliation scan for deleted items
--states string Filter to ADO states, comma-separated (e.g., "New,Active,Resolved")
--types string Filter to work item types, comma-separated (e.g., "Bug,Task,User Story")
```

View file

@ -0,0 +1,20 @@
---
title: "bd assign"
description: "Assign an issue to someone"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc assign`.
Assign an issue to someone.
Shorthand for 'bd update &lt;id&gt; --assignee &lt;name&gt;'.
Examples:
bd assign bd-123 alice
bd assign bd-123 "" # unassign
```
bd assign <id> <name> [flags]
```

View file

@ -0,0 +1,57 @@
---
title: "bd audit"
description: "Record and label agent interactions (append-only JSONL)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc audit`.
Audit log entries are appended to .beads/interactions.jsonl.
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 [flags]
```
## bd audit label
Append a label entry referencing an existing interaction
```
bd audit label <entry-id> [flags]
```
**Flags:**
```
--label string Label value (e.g. "good" or "bad")
--reason string Reason for label
```
## bd audit record
Append an audit interaction entry
```
bd audit record [flags]
```
**Flags:**
```
--error string Error string (llm_call/tool_call)
--exit-code int Exit code (tool_call) (default -1)
--issue-id string Related issue id (bd-...)
--kind string Entry kind (e.g. llm_call, tool_call, label)
--model string Model name (llm_call)
--prompt string Prompt text (llm_call)
--response string Response text (llm_call)
--stdin Read a JSON object from stdin (must match audit.Entry schema)
--tool-name string Tool name (tool_call)
```

View file

@ -0,0 +1,115 @@
---
title: "bd backup"
description: "Back up your beads database"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc backup`.
Back up your beads database for off-machine recovery.
This is a Dolt-native database backup. It preserves the database state,
including tables, branches, commit history, and working-set data. This is
different from 'bd export', which writes issue records to JSONL for migration
and interoperability.
Commands:
bd backup init &lt;path&gt; Set up a backup destination (filesystem or DoltHub)
bd backup sync Push to configured backup destination
bd backup restore [path] Restore from a backup directory
bd backup remove Remove backup destination
bd backup status Show backup status
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.
```
bd backup [flags]
```
## bd backup init
Configure a filesystem path or URL as a backup destination.
The path can be a local directory (external drive, NAS, Dropbox folder) or a
DoltHub remote URL. If the destination was previously configured, it is
updated to the new path.
Filesystem examples:
bd backup add /mnt/usb/beads-backup
bd backup add ~/Dropbox/beads-backup
DoltHub (recommended for cloud backup):
bd backup add https://doltremoteapi.dolthub.com/myuser/beads-backup
After adding, run 'bd backup sync' to push your data.
```
bd backup init <path> [flags]
```
**Aliases:** add
## bd backup remove
Remove the configured backup destination.
This unregisters the backup remote from Dolt and removes the local
backup configuration. The backup data at the destination is not deleted.
```
bd backup remove [flags]
```
**Aliases:** rm
## bd backup restore
Restore the beads database from a Dolt-native backup.
By default, reads from .beads/backup/ (or the configured backup directory).
Optionally specify a path to a directory containing a Dolt backup.
This restores a full database backup created by 'bd backup sync' or an
equivalent Dolt backup. JSONL files produced by 'bd export' are issue exports,
not restore targets for this command.
Use --force to overwrite an existing database with the backup contents.
The database must already be initialized (run 'bd init' first if needed).
To initialize and restore in one step, use: bd init &amp;&amp; bd backup restore
```
bd backup restore [path] [flags]
```
**Flags:**
```
--force Overwrite existing database with backup contents
```
## bd backup status
Show last backup status
```
bd backup status [flags]
```
## bd backup sync
Sync the current beads database to the configured Dolt backup destination.
This pushes the entire database state (all branches, full history) to the
backup location configured with 'bd backup init'.
The backup is atomic — if the sync fails, the previous backup state is preserved.
Run 'bd backup init &lt;path&gt;' first to configure a destination.
```
bd backup sync [flags]
```

View file

@ -0,0 +1,62 @@
---
title: "bd batch"
description: "Run multiple write operations in a single database transaction"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc batch`.
Run multiple write operations in a single database transaction.
Commands are read from stdin (one per line) or from a file via -f/--file.
All operations execute inside a single dolt transaction: on any error the
whole batch is rolled back, otherwise it is committed with one DOLT_COMMIT.
This is intended for shell scripts that currently invoke 'bd' many times in
a loop, which causes severe write amplification on a dolt sql-server backed
by btrfs+compression. Batching collapses N invocations into one transaction
and one dolt commit.
Grammar (one command per line):
close &lt;id&gt; [reason...]
update &lt;id&gt; &lt;key&gt;=&lt;value&gt; [&lt;key&gt;=&lt;value&gt; ...]
create &lt;type&gt; &lt;priority&gt; &lt;title...&gt;
dep add &lt;from-id&gt; &lt;to-id&gt; [type]
dep remove &lt;from-id&gt; &lt;to-id&gt;
#comment (blank lines and '# ...' comments are ignored)
Supported 'update' keys: status, priority, title, assignee
Supported dependency types: see 'bd dep add --help' (default: blocks)
Tokens are whitespace-separated. Double-quoted strings ("like this") may
contain spaces; use \" to embed a quote and \\ for a backslash.
Examples:
# From a pipe
bd list --status stale -q | awk '&#123;print "close",$1," stale"&#125;' | bd batch
# From a file
bd batch -f operations.txt
# Inline
printf 'close bd-1 done\nupdate bd-2 status=in_progress\n' | bd batch
On success, exits 0 and prints a summary (or JSON with --json). On any error,
rolls back the entire transaction and exits non-zero with the failing line.
NOTE: This is a narrow subset. Commands like 'show', 'list', 'ready', 'sync',
complex create flows, or any flag not listed above are NOT accepted. Use
normal 'bd' subcommands for interactive/read operations.
```
bd batch [flags]
```
**Flags:**
```
--dry-run Parse input and echo commands without executing
-f, --file string Read commands from file instead of stdin
-m, --message string DOLT_COMMIT message (default: 'bd: batch N ops by <actor>')
```

View file

@ -0,0 +1,20 @@
---
title: "bd blocked"
description: "Show blocked issues"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc blocked`.
Show blocked issues
```
bd blocked [flags]
```
**Flags:**
```
--parent string Filter to descendants of this bead/epic
```

View file

@ -0,0 +1,47 @@
---
title: "bd bootstrap"
description: "Non-destructive database setup for fresh clones and recovery"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc bootstrap`.
Bootstrap sets up the beads database without destroying existing data.
Unlike 'bd init --force', bootstrap will never delete existing issues.
Bootstrap auto-detects the right action:
• If sync.remote is configured: clones from the remote
• If git origin has Dolt data (refs/dolt/data): clones from git and wires origin for future push/pull
• If .beads/backup/*.jsonl exists: restores from backup
• If .beads/issues.jsonl exists: imports from git-tracked JSONL
• If no database exists: creates a fresh one
• If database already exists: validates and reports status
This is the recommended command for:
• Setting up beads on a fresh clone
• Recovering after moving to a new machine
• Repairing a broken database configuration
Non-interactive mode (--non-interactive, --yes/-y, or BD_NON_INTERACTIVE=1):
Skips the confirmation prompt before executing the bootstrap plan.
Also auto-detected when stdin is not a terminal or CI=true is set.
Examples:
bd bootstrap # Auto-detect and set up
bd bootstrap --dry-run # Show what would be done
bd bootstrap --json # Output plan as JSON
bd bootstrap --yes # Skip confirmation prompt
```
bd bootstrap [flags]
```
**Flags:**
```
--dry-run Show what would be done without doing it
--non-interactive Alias for --yes
-y, --yes Skip confirmation prompts (for CI/automation)
```

View file

@ -0,0 +1,21 @@
---
title: "bd branch"
description: "List or create branches"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc branch`.
List all branches or create a new branch.
This command requires the Dolt storage backend. Without arguments,
it lists all branches. With an argument, it creates a new branch.
Examples:
bd branch # List all branches
bd branch feature-xyz # Create a new branch named feature-xyz
```
bd branch [name] [flags]
```

View file

@ -0,0 +1,29 @@
---
title: "bd children"
description: "List child beads of a parent"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc children`.
List all beads that are children of the specified parent bead.
This is a convenience alias for 'bd list --parent &lt;id&gt; --status all'.
Unlike plain 'bd list', children includes closed issues by default,
since the primary use case is inspecting all work under a parent.
Examples:
bd children hq-abc123 # List all children of hq-abc123
bd children hq-abc123 --json # List children in JSON format
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -0,0 +1,37 @@
---
title: "bd close"
description: "Close one or more issues"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc close`.
Close one or more issues.
If no issue ID is provided, closes the last touched issue (from most recent
create, update, show, or close operation).
When closing multiple issues, provide one --reason for all IDs or repeat
--reason once per ID. Reasons map positionally: the first --reason applies
to the first ID, the second --reason to the second ID, regardless of where
the flags appear in the command line.
```
bd close [id...] [flags]
```
**Aliases:** done
**Flags:**
```
--claim-next Automatically claim the next highest priority available issue
--continue Auto-advance to next step in molecule
-f, --force Force close pinned issues or unsatisfied gates
--no-auto With --continue, show next step but don't claim it
-r, --reason string Reason for closing
--reason-file string Read close reason from file (use - for stdin)
--session string Claude Code session ID (or set CLAUDE_SESSION_ID env var)
--suggest-next Show newly unblocked issues after closing
```

View file

@ -0,0 +1,29 @@
---
title: "bd comment"
description: "Add a comment to an issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc comment`.
Add a comment to an issue.
Shorthand for 'bd comments add &lt;id&gt; "text"'.
Examples:
bd comment bd-123 "Working on this now"
bd comment bd-123 Working on this now
echo "comment from pipe" | bd comment bd-123 --stdin
bd comment bd-123 --file notes.txt
```
bd comment <id> [text...] [flags]
```
**Flags:**
```
--file string Read comment text from file
--stdin Read comment text from stdin
```

View file

@ -0,0 +1,63 @@
---
title: "bd comments"
description: "View or manage comments on an issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc comments`.
View or manage comments on an issue.
Examples:
# List all comments on an issue (issue id is required — there is no "comments list")
bd comments bd-123
# List comments in JSON format
bd comments bd-123 --json
# Add a comment
bd comments add bd-123 "This is a comment"
# Add a comment from a file
bd comments add bd-123 -f notes.txt
```
bd comments [issue-id] [flags]
```
**Flags:**
```
--local-time Show timestamps in local time instead of UTC
```
## bd comments add
Add a comment to an issue.
Examples:
# Add a comment
bd comments add bd-123 "Working on this now"
# Add a comment from a file
bd comments add bd-123 -f notes.txt
```
bd comments add [issue-id] [text] [flags]
```
**Flags:**
```
-a, --author string Add author to comment
-f, --file string Read comment text from file
```
## bd comments list
Invalid — use bd comments &lt;issue-id&gt; to list comments
```
bd comments list [flags]
```

View file

@ -0,0 +1,42 @@
---
title: "bd compact"
description: "Squash old Dolt commits to reduce history size"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc compact`.
Squash Dolt commits older than N days into a single commit.
Recent commits (within the retention window) are preserved via cherry-pick.
This reduces Dolt storage overhead from auto-commit history while keeping
recent change tracking intact.
For semantic issue compaction (summarizing closed issues), use 'bd admin compact'.
For full history squash, use 'bd flatten'.
How it works:
1. Identifies commits older than --days threshold
2. Creates a squashed base commit from all old history
3. Cherry-picks recent commits on top
4. Swaps main branch to the compacted version
5. Runs Dolt GC to reclaim space
Examples:
bd compact --dry-run # Preview: show commit breakdown
bd compact --force # Squash commits older than 30 days
bd compact --days 7 --force # Keep only last 7 days of history
bd compact --days 90 --force # Conservative: squash 90+ day old commits
```
bd compact [flags]
```
**Flags:**
```
--days int Keep commits newer than N days (default 30)
--dry-run Preview without making changes
-f, --force Confirm commit squash
```

View file

@ -0,0 +1,133 @@
---
title: "bd completion"
description: "Generate the autocompletion script for the specified shell"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc completion`.
Generate the autocompletion script for bd for the specified shell.
See each sub-command's help for details on how to use the generated script.
```
bd completion [flags]
```
## bd completion bash
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source &lt;(bd completion bash)
To load completions for every new session, execute once:
#### Linux:
bd completion bash &gt; /etc/bash_completion.d/bd
#### macOS:
bd completion bash &gt; $(brew --prefix)/etc/bash_completion.d/bd
You will need to start a new shell for this setup to take effect.
```
bd completion bash
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
## bd completion fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
bd completion fish | source
To load completions for every new session, execute once:
bd completion fish &gt; ~/.config/fish/completions/bd.fish
You will need to start a new shell for this setup to take effect.
```
bd completion fish [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
## bd completion powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
bd completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command
to your powershell profile.
```
bd completion powershell [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
## bd completion zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" &gt;&gt; ~/.zshrc
To load completions in your current shell session:
source &lt;(bd completion zsh)
To load completions for every new session, execute once:
#### Linux:
bd completion zsh &gt; "$&#123;fpath[1]&#125;/_bd"
#### macOS:
bd completion zsh &gt; $(brew --prefix)/share/zsh/site-functions/_bd
You will need to start a new shell for this setup to take effect.
```
bd completion zsh [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```

View file

@ -0,0 +1,243 @@
---
title: "bd config"
description: "Manage configuration settings"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc config`.
Manage configuration settings for external integrations and preferences.
Configuration is stored per-project in the beads database and is version-control-friendly.
Common namespaces:
- export.* Auto-export settings (stored in config.yaml)
- import.* JSONL import settings (stored in config.yaml)
- 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
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: false)
Auto-Import (config.yaml):
Reads .beads/issues.jsonl by default when a JSONL import path is implied.
Use a relative filename/path so the import stays within the project .beads/
directory and remains portable across machines.
Keys:
import.path Input filename relative to .beads/ (default: issues.jsonl)
Custom Status States:
You can define custom status states for multi-step pipelines using the
status.custom config key. Statuses should be comma-separated.
Example:
bd config set status.custom "awaiting_review,awaiting_testing,awaiting_docs"
This enables issues to use statuses like 'awaiting_review' in addition to
the built-in statuses (open, in_progress, blocked, deferred, closed).
Suppressing Doctor Warnings:
Suppress specific bd doctor warnings by check name slug:
bd config set doctor.suppress.pending-migrations true
bd config set doctor.suppress.git-hooks true
Check names are converted to slugs: "Git Hooks" → "git-hooks".
Only warnings are suppressed (errors and passing checks always show).
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set import.path "beads.jsonl" # Custom import filename
bd config set export.git-add true # Also stage the export file
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 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
bd config get export.auto
bd config list
bd config unset jira.url
```
bd config [flags]
```
## bd config apply
Reconcile actual system state to match declared configuration.
Runs drift detection and then fixes any mismatches it finds:
- hooks Reinstall git hooks if missing or outdated
- remote Add/update Dolt origin remote to match federation.remote
- server Start Dolt server if dolt.shared-server is enabled
This command is idempotent — safe to run multiple times. Use --dry-run
to preview what would change without making modifications.
Examples:
bd config apply
bd config apply --dry-run
bd config apply --json
```
bd config apply [flags]
```
**Flags:**
```
--dry-run Show what would change without making modifications
```
## bd config drift
Detect drift between declared configuration and actual system state.
This is a read-only diagnostic that answers "is my environment consistent
with my config?" — no mutations are performed.
Checks:
- hooks Git hooks installed and up-to-date
- remote Dolt remote matches federation.remote config
- server Server state matches dolt.shared-server config
Exit codes:
0 No drift detected (all checks ok/info/skipped)
1 Drift detected (at least one check has status "drift")
Examples:
bd config drift
bd config drift --json
```
bd config drift [flags]
```
## bd config get
Get a configuration value
```
bd config get <key> [flags]
```
## bd config list
List all configuration
```
bd config list [flags]
```
## bd config set
Set a configuration value
```
bd config set <key> <value> [flags]
```
**Flags:**
```
--force-git-tracked Allow writing secret keys to git-tracked config files (use with caution)
```
## bd config set-many
Set multiple configuration values at once with a single auto-commit and auto-push.
Each argument must be in key=value format. All values are validated before
any writes occur. This is faster and less noisy than separate 'bd config set'
calls, especially in CI.
Examples:
bd config set-many ado.state_map.open=New ado.state_map.closed=Closed
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ
```
bd config set-many <key=value>... [flags]
```
**Flags:**
```
--force-git-tracked Allow writing secret keys to git-tracked config files (use with caution)
```
## bd config show
Display a unified view of all effective configuration across all sources
with annotations showing where each value comes from.
Sources (by precedence for Viper-managed keys):
- env Environment variable (BD_* or BEADS_*)
- config.yaml Project config file (.beads/config.yaml)
- default Built-in default value
Additional sources:
- metadata Connection settings from .beads/metadata.json
- database Integration config stored in the Dolt database
- git Git config (e.g., beads.role)
Examples:
bd config show
bd config show --json
bd config show --source config.yaml
```
bd config show [flags]
```
**Flags:**
```
--source string Filter by source (e.g., config.yaml, env, default, metadata, database, git)
```
## bd config unset
Delete a configuration value
```
bd config unset <key> [flags]
```
## bd config validate
Validate sync-related configuration settings.
Checks:
- federation.sovereignty is valid (T1, T2, T3, T4, or empty)
- federation.remote is set for Dolt sync
- Remote URL format is valid (dolthub://, gs://, s3://, az://, file://)
- routing.mode is valid (auto, maintainer, contributor, explicit)
Examples:
bd config validate
bd config validate --json
```
bd config validate [flags]
```

View file

@ -0,0 +1,23 @@
---
title: "bd context"
description: "Show effective backend identity and repository context"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc context`.
Show the effective backend identity information including repository paths,
backend configuration, and sync settings.
This command reads directly from config files and does not require the
database to be open, making it useful for diagnostics in degraded states.
Examples:
bd context # Show context information
bd context --json # Output in JSON format
```
bd context [flags]
```

View file

@ -0,0 +1,72 @@
---
title: "bd cook"
description: "Compile a formula into a proto (ephemeral by default)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc cook`.
Cook transforms a .formula.json file into a proto.
By default, cook outputs the resolved formula as JSON to stdout for
ephemeral use. The output can be inspected, piped, or saved to a file.
Two cooking modes are available:
COMPILE-TIME (default, --mode=compile):
Produces a proto with &#123;&#123;variable&#125;&#125; placeholders intact.
Use for: modeling, estimation, contractor handoff, planning.
Variables are NOT substituted - the output shows the template structure.
RUNTIME (--mode=runtime or when --var flags provided):
Produces a fully-resolved proto with variables substituted.
Use for: final validation before pour, seeing exact output.
Requires all variables to have values (via --var or defaults).
Formulas are high-level workflow templates that support:
- Variable definitions with defaults and validation
- Step definitions that become issue hierarchies
- Composition rules for bonding formulas together
- Inheritance via extends
The --persist flag enables the legacy behavior of writing the proto
to the database. This is useful when you want to reuse the same
proto multiple times without re-cooking.
For most workflows, prefer ephemeral protos: pour and wisp commands
accept formula names directly and cook inline.
Examples:
bd cook mol-feature.formula.json # Compile-time: keep &#123;&#123;vars&#125;&#125;
bd cook mol-feature --var name=auth # Runtime: substitute vars
bd cook mol-feature --mode=runtime --var name=auth # Explicit runtime mode
bd cook mol-feature --dry-run # Preview steps
bd cook mol-release.formula.json --persist # Write to database
bd cook mol-release.formula.json --persist --force # Replace existing
Output (default):
JSON representation of the resolved formula with all steps.
Output (--persist):
Creates a proto bead in the database with:
- ID matching the formula name (e.g., mol-feature)
- The "template" label for proto identification
- Child issues for each step
- Dependencies matching depends_on relationships
```
bd cook <formula-file> [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--force Replace existing proto if it exists (requires --persist)
--mode string Cooking mode: compile (keep placeholders) or runtime (substitute vars)
--persist Persist proto to database (legacy behavior)
--prefix string Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature')
--search-path strings Additional paths to search for formula inheritance
--var stringArray Variable substitution (key=value), enables runtime mode
```

View file

@ -0,0 +1,62 @@
---
title: "bd count"
description: "Count issues matching filters"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc count`.
Count issues matching the specified filters.
By default, returns the total count of issues matching the filters.
Use --by-* flags to group counts by different attributes.
Examples:
bd count # Count all issues
bd count --status open # Count open issues
bd count --by-status # Group count by status
bd count --by-priority # Group count by priority
bd count --by-type # Group count by issue type
bd count --by-assignee # Group count by assignee
bd count --by-label # Group count by label
bd count --assignee alice --by-status # Count alice's issues by status
bd count --include-infra # Count issues + wisps tier (matches 'bd list --include-infra --all' cardinality)
```
bd count [flags]
```
**Flags:**
```
-a, --assignee string Filter by assignee
--by-assignee Group count by assignee
--by-label Group count by label
--by-priority Group count by priority
--by-status Group count by status
--by-type Group count by issue type
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--desc-contains string Filter by description substring
--empty-description Filter issues with empty description
--id string Filter by specific issue IDs (comma-separated)
--include-infra Include infrastructure beads and the wisps tier (matches 'bd list --include-infra --all' cardinality)
-l, --label strings Filter by labels (AND: must have ALL)
--label-any strings Filter by labels (OR: must have AT LEAST ONE)
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--notes-contains string Filter by notes substring
-p, --priority int Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
--priority-max int Filter by maximum priority (inclusive)
--priority-min int Filter by minimum priority (inclusive)
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues use 'bd blocked'
--title string Filter by title text (case-insensitive substring match)
--title-contains string Filter by title substring
-t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
```

View file

@ -0,0 +1,32 @@
---
title: "bd create-form"
description: "Create a new issue using an interactive form"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc create-form`.
Create a new issue using an interactive terminal form.
This command provides a user-friendly form interface for creating issues,
with fields for title, description, type, priority, labels, and more.
Use --parent to create a sub-issue under an existing parent issue.
The child will get an auto-generated hierarchical ID (e.g., parent-id.1).
The form uses keyboard navigation:
- Tab/Shift+Tab: Move between fields
- Enter: Submit the form (on the last field or submit button)
- Ctrl+C: Cancel and exit
- Arrow keys: Navigate within select fields
```
bd create-form [flags]
```
**Flags:**
```
--parent string Parent issue ID for creating a hierarchical child (e.g., 'bd-a3f8e9')
```

View file

@ -0,0 +1,64 @@
---
title: "bd create"
description: "Create a new issue (or batch from markdown/graph JSON)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc create`.
Create a new issue (or batch from markdown/graph JSON)
```
bd create [title] [flags]
```
**Aliases:** new
**Flags:**
```
--acceptance string Acceptance criteria
--append-notes string Append to existing notes (with newline separator)
-a, --assignee string Assignee
--body-file string Read description from file (use - for stdin)
--context string Additional context for the issue
--defer string Defer until date (issue hidden from bd ready until then). Same formats as --due
--deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
-d, --description string Issue description
--design string Design notes
--design-file string Read design from file (use - for stdin)
--dry-run Preview what would be created without actually creating
--due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
--ephemeral Create as ephemeral (short-lived, subject to TTL compaction)
-e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour)
--event-actor string Entity URI who caused this event (requires --type=event)
--event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event)
--event-payload string Event-specific JSON data (requires --type=event)
--event-target string Entity URI or bead ID affected (requires --type=event)
--external-ref string External reference (e.g., 'gh-9', 'jira-ABC', Linear URL)
-f, --file string Create multiple issues from markdown file
--force Force creation even if prefix doesn't match database prefix
--graph string Create a graph of issues with dependencies from JSON plan file
--id string Explicit issue ID (e.g., 'bd-42' for partitioning)
-l, --labels strings Labels (comma-separated)
--metadata string Set custom metadata (JSON string or @file.json to read from file)
--mol-type string Molecule type: swarm (multi-agent), patrol (recurring ops), work (default)
--no-history Skip Dolt commit history without making GC-eligible (for permanent agent beads)
--no-inherit-labels Don't inherit labels from parent issue
--notes string Additional notes
--parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
-p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2")
--repo string Target repository for issue (overrides auto-routing)
--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")
--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")
--wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
```

View file

@ -0,0 +1,34 @@
---
title: "bd defer"
description: "Defer one or more issues for later"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc defer`.
Defer issues to put them on ice for later.
Deferred issues are deliberately set aside - not blocked by anything specific,
just postponed for future consideration. Unlike blocked issues, there's no
dependency keeping them from being worked. Unlike closed issues, they will
be revisited.
Deferred issues don't show in 'bd ready' but remain visible in 'bd list'.
Examples:
bd defer bd-abc # Defer a single issue (status-based)
bd defer bd-abc --until=tomorrow # Defer until specific time
bd defer bd-abc --reason="waiting on API access"
bd defer bd-abc bd-def # Defer multiple issues
```
bd defer [id...] [flags]
```
**Flags:**
```
--reason string Record why this issue is being deferred (appended to notes)
--until string Defer until specific time (e.g., +1h, tomorrow, next monday)
```

View file

@ -0,0 +1,49 @@
---
title: "bd delete"
description: "Delete one or more issues and clean up references"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc delete`.
Delete one or more issues and clean up all references to them.
This command will:
1. Remove all dependency links (any type, both directions) involving the issues
2. Update text references to "[deleted:ID]" in directly connected issues
3. Permanently delete the issues from the database
This is a destructive operation that cannot be undone. Use with caution.
BATCH DELETION:
Delete multiple issues at once:
bd delete bd-1 bd-2 bd-3 --force
Delete from file (one ID per line):
bd delete --from-file deletions.txt --force
Preview before deleting:
bd delete --from-file deletions.txt --dry-run
DEPENDENCY HANDLING:
Default: Fails if any issue has dependents not in deletion set
bd delete bd-1 bd-2
Cascade: Recursively delete all dependents
bd delete bd-1 --cascade --force
Force: Delete and orphan dependents
bd delete bd-1 --force
```
bd delete <issue-id> [issue-id...] [flags]
```
**Flags:**
```
--cascade Recursively delete all dependent issues
--dry-run Preview what would be deleted without making changes
-f, --force Actually delete (without this flag, shows preview)
--from-file string Read issue IDs from file (one per line)
```

183
docs/cli-reference/dep.md Normal file
View file

@ -0,0 +1,183 @@
---
title: "bd dep"
description: "Manage dependencies"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc dep`.
Manage dependencies between issues.
When called with an issue ID and --blocks flag, creates a blocking dependency:
bd dep &lt;blocker-id&gt; --blocks &lt;blocked-id&gt;
This is equivalent to:
bd dep add &lt;blocked-id&gt; &lt;blocker-id&gt;
Examples:
bd dep bd-xyz --blocks bd-abc # bd-xyz blocks bd-abc
bd dep add bd-abc bd-xyz # Same as above (bd-abc depends on bd-xyz)
```
bd dep [issue-id] [flags]
```
**Flags:**
```
-b, --blocks string Issue ID that this issue blocks (shorthand for: bd dep add <blocked> <blocker>)
--no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit
```
## bd dep add
Add a dependency between two issues.
The depends-on-id can be provided as:
- A positional argument: bd dep add issue-123 issue-456
- A flag: bd dep add issue-123 --blocked-by issue-456
- A flag: bd dep add issue-123 --depends-on issue-456
The --blocked-by and --depends-on flags are aliases and both mean "issue-123
depends on (is blocked by) the specified issue."
The depends-on-id can be:
- A local issue ID (e.g., bd-xyz)
- An external reference: external:&lt;project&gt;:&lt;capability&gt;
For bulk wiring, pass newline-delimited JSON with --file. Each line must be an
object with "from" and "to" fields, and may include "type". The aliases
"issue_id" and "depends_on_id" are also accepted. Use --file - to read stdin.
External references are stored as-is and resolved at query time using
the external_projects config. They block the issue until the capability
is "shipped" in the target project.
Examples:
bd dep add bd-42 bd-41 # Positional args
bd dep add bd-42 --blocked-by bd-41 # Flag syntax (same effect)
bd dep add bd-42 --depends-on bd-41 # Alias (same effect)
bd dep add gt-xyz external:beads:mol-run-assignee # Cross-project dependency
bd dep add bd-42 bd-41 --no-cycle-check # Skip cycle check (bulk wiring)
bd dep add --file deps.jsonl # Bulk JSONL: &#123;"from":"bd-42","to":"bd-41"&#125;
```
bd dep add [issue-id] [depends-on-id] [flags]
```
**Flags:**
```
--blocked-by string Issue ID that blocks the first issue (alternative to positional arg)
--depends-on string Issue ID that the first issue depends on (alias for --blocked-by)
--file string Read dependency edges from JSONL file, or '-' for stdin
--no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit
-t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes) (default "blocks")
```
## bd dep cycles
Detect dependency cycles
```
bd dep cycles [flags]
```
## bd dep list
List dependencies or dependents of one or more issues with optional type filtering.
By default shows dependencies (what issues depend on). Use --direction to control:
- down: Show dependencies (what this issue depends on) - default
- up: Show dependents (what depends on this issue)
Multiple IDs can be provided for batch dep listing. With --json, the output
is a flat array of dependency records across all requested issues.
Use --type to filter by dependency type (e.g., tracks, blocks, parent-child).
Examples:
bd dep list gt-abc # Show what gt-abc depends on
bd dep list gt-abc gt-def # Batch: deps for both issues
bd dep list gt-abc --direction=up # Show what depends on gt-abc
bd dep list gt-abc --direction=up -t tracks # Show what tracks gt-abc (convoy tracking)
```
bd dep list [issue-id...] [flags]
```
**Flags:**
```
--direction string Direction: 'down' (dependencies), 'up' (dependents) (default "down")
-t, --type string Filter by dependency type (e.g., tracks, blocks, parent-child)
```
## bd dep relate
Create a loose 'see also' relationship between two issues.
The relates_to link is bidirectional - both issues will reference each other.
This enables knowledge graph connections without blocking or hierarchy.
Examples:
bd relate bd-abc bd-xyz # Link two related issues
bd relate bd-123 bd-456 # Create see-also connection
```
bd dep relate <id1> <id2> [flags]
```
## bd dep remove
Remove a dependency
```
bd dep remove [issue-id] [depends-on-id] [flags]
```
**Aliases:** rm
## bd dep tree
Show dependency tree rooted at the given issue.
By default, shows dependencies (what blocks this issue). Use --direction to control:
- down: Show dependencies (what blocks this issue) - default
- up: Show dependents (what this issue blocks)
- both: Show full graph in both directions
Examples:
bd dep tree gt-0iqq # Show what blocks gt-0iqq
bd dep tree gt-0iqq --direction=up # Show what gt-0iqq blocks
bd dep tree gt-0iqq --status=open # Only show open issues
bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep
```
bd dep tree [issue-id] [flags]
```
**Flags:**
```
--direction string Tree direction: 'down' (dependencies), 'up' (dependents), or 'both'
--format string Output format: 'mermaid' for Mermaid.js flowchart
-d, --max-depth int Maximum tree depth to display (safety limit) (default 50)
--reverse Show dependent tree (deprecated: use --direction=up)
--show-all-paths Show all paths to nodes (no deduplication for diamond dependencies)
--status string Filter to only show issues with this status (open, in_progress, blocked, deferred, closed)
```
## bd dep unrelate
Remove a relates_to relationship between two issues.
Removes the link in both directions.
Example:
bd unrelate bd-abc bd-xyz
```
bd dep unrelate <id1> <id2> [flags]
```

View file

@ -0,0 +1,24 @@
---
title: "bd diff"
description: "Show changes between two commits or branches"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc diff`.
Show the differences in issues between two commits or branches.
The refs can be:
- Commit hashes (e.g., abc123def)
- Branch names (e.g., main, feature-branch)
- Special refs like HEAD, HEAD~1
Examples:
bd diff main feature-branch # Compare main to feature branch
bd diff HEAD~5 HEAD # Show changes in last 5 commits
bd diff abc123 def456 # Compare two specific commits
```
bd diff <from-ref> <to-ref> [flags]
```

View file

@ -0,0 +1,150 @@
---
title: "bd doctor"
description: "Check and fix beads installation health (start here)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc doctor`.
Sanity check the beads installation for the current directory or specified path.
This command checks:
- If .beads/ directory exists
- Database version and migration status
- Schema compatibility (all required tables and columns present)
- Whether using hash-based vs sequential IDs
- If CLI version is current (checks GitHub releases)
- If Claude plugin is current (when running in Claude Code)
- File permissions
- Circular dependencies
- Git hooks (pre-commit, post-merge, pre-push)
- .beads/.gitignore up to date
- Metadata.json version tracking (LastBdVersion field)
Performance Mode (--perf):
Run performance diagnostics on your database:
- Times key operations (bd ready, bd list, bd show, etc.)
- Collects system info (OS, arch, SQLite version, database stats)
- Generates CPU profile for analysis
- Outputs shareable report for bug reports
Export Mode (--output):
Save diagnostics to a JSON file for historical analysis and bug reporting.
Includes timestamp and platform info for tracking intermittent issues.
Specific Check Mode (--check):
Run a specific check in detail. Available checks:
- artifacts: Detect and optionally clean beads classic artifacts
(stale JSONL, SQLite files, cruft .beads dirs). Use with --clean.
- conventions: Check for convention drift (lint warnings, stale
issues, orphaned issues). Advisory only - warns, never blocks.
- pollution: Detect and optionally clean test issues from database
- validate: Run focused data-integrity checks (duplicates, orphaned
deps, test pollution, git conflicts). Use with --fix to auto-repair.
Deep Validation Mode (--deep):
Validate full graph integrity. May be slow on large databases.
Additional checks:
- Parent consistency: All parent-child deps point to existing issues
- Dependency integrity: All deps reference valid issues
- Epic completeness: Find epics ready to close (all children closed)
- Agent bead integrity: Agent beads have valid state values
- Mail thread integrity: Thread IDs reference existing issues
- Molecule integrity: Molecules have valid parent-child structures
Server Mode (--server):
Run health checks for Dolt server mode connections (bd-dolt.2.3):
- Server reachable: Can connect to configured host:port?
- Dolt version: Is it a Dolt server (not vanilla MySQL)?
- Database exists: Does the 'beads' database exist?
- Schema compatible: Can query beads tables?
- Connection pool: Pool health metrics
Migration Validation Mode (--migration):
Run Dolt migration validation checks with machine-parseable output.
Use --migration=pre before migration to verify readiness:
- JSONL file exists and is valid (parseable, no corruption)
- All JSONL issues are present in SQLite (or explains discrepancies)
- No blocking issues prevent migration
Use --migration=post after migration to verify completion:
- Dolt database exists and is healthy
- All issues from JSONL are present in Dolt
- No data was lost during migration
- Dolt database has no locks or uncommitted changes
Combine with --json for machine-parseable output for automation.
Agent Mode (--agent):
Output diagnostics designed for AI agent consumption. Instead of terse
pass/fail messages, each issue includes:
- Observed state: what the system actually looks like
- Expected state: what it should look like
- Explanation: full prose context about the issue and why it matters
- Commands: exact remediation commands to run
- Source files: where in the codebase to investigate further
- Severity: blocking (prevents operation), degraded (partial function),
or advisory (informational only)
ZFC-compliant: Go observes and reports, the agent decides and acts.
Combine with --json for structured agent-facing output.
Suppressing Warnings:
Suppress specific warnings by setting doctor.suppress.&lt;check-slug&gt; config:
bd config set doctor.suppress.pending-migrations true
bd config set doctor.suppress.git-hooks true
Check names are converted to slugs: "Git Hooks" → "git-hooks".
Only warnings are suppressed; errors and passing checks always show.
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd doctor # Check current directory
bd doctor /path/to/repo # Check specific repository
bd doctor --json # Machine-readable output
bd doctor --agent # Agent-facing diagnostic output
bd doctor --agent --json # Structured agent diagnostics (JSON)
bd doctor --fix # Automatically fix issues (with confirmation)
bd doctor --fix --yes # Automatically fix issues (no confirmation)
bd doctor --fix -i # Confirm each fix individually
bd doctor --fix --fix-child-parent # Also fix child→parent deps (opt-in)
bd doctor --fix --force # Force repair even when database can't be opened
bd doctor --fix --source=jsonl # Rebuild database from a JSONL export
bd doctor --dry-run # Preview what --fix would do without making changes
bd doctor --perf # Performance diagnostics
bd doctor --output diagnostics.json # Export diagnostics to file
bd doctor --check=artifacts # Show classic artifacts (JSONL, SQLite, cruft dirs)
bd doctor --check=artifacts --clean # Delete safe-to-delete artifacts (with confirmation)
bd doctor --check=conventions # Convention drift check (lint, stale, orphans)
bd doctor --check=pollution # Show potential test issues
bd doctor --check=pollution --clean # Delete test issues (with confirmation)
bd doctor --check=validate # Data-integrity checks only
bd doctor --check=validate --fix # Auto-fix data-integrity issues
bd doctor --deep # Full graph integrity validation
bd doctor --server # Dolt server mode health checks
bd doctor --migration=pre # Validate readiness for Dolt migration
bd doctor --migration=post # Validate Dolt migration completed
bd doctor --migration=pre --json # Machine-parseable migration validation
```
bd doctor [path] [flags]
```
**Flags:**
```
--agent Agent-facing diagnostic mode: rich context for AI agents (ZFC-compliant)
--check string Run specific check in detail (e.g., 'pollution')
--check-health Quick health check for git hooks (silent on success)
--clean For pollution check: delete detected test issues
--deep Validate full graph integrity
--dry-run Preview fixes without making changes
--fix Automatically fix issues where possible
--fix-child-parent Remove child→parent dependencies (opt-in)
-i, --interactive Confirm each fix individually
--migration string Run Dolt migration validation: 'pre' (before migration) or 'post' (after migration)
--orchestrator Running in orchestrator multi-workspace mode (routes.jsonl is expected, higher duplicate tolerance)
--orchestrator-duplicates-threshold int Duplicate tolerance threshold for orchestrator mode (wisps are ephemeral) (default 1000)
-o, --output string Export diagnostics to JSON file
--perf Run performance diagnostics and generate CPU profile
--server Run Dolt server mode health checks (connectivity, version, schema)
-v, --verbose Show all checks (default shows only warnings/errors)
-y, --yes Skip confirmation prompt (for non-interactive use)
```

301
docs/cli-reference/dolt.md Normal file
View file

@ -0,0 +1,301 @@
---
title: "bd dolt"
description: "Configure Dolt database settings"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc dolt`.
Configure and manage Dolt database settings and server lifecycle.
Beads uses a dolt sql-server for all database operations. The server is
auto-started transparently when needed. Use these commands for explicit
control or diagnostics.
Server lifecycle:
bd dolt start Start the Dolt server for this project
bd dolt stop Stop the Dolt server for this project
bd dolt status Show Dolt server status
Configuration:
bd dolt show Show current Dolt configuration with connection test
bd dolt set &lt;k&gt; &lt;v&gt; Set a configuration value
bd dolt test Test server connection
Version control:
bd dolt commit Commit pending changes
bd dolt push Push commits to Dolt remote
bd dolt pull Pull commits from Dolt remote
Remote management:
bd dolt remote add &lt;name&gt; &lt;url&gt; Add a Dolt remote
bd dolt remote list List configured remotes
bd dolt remote remove &lt;name&gt; Remove a Dolt remote
Configuration keys for 'bd dolt set':
database Database name (default: issue prefix or "beads")
host Server host (default: 127.0.0.1)
port Server port (auto-detected; override with bd dolt set port &lt;N&gt;)
user MySQL user (default: root)
data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
Flags for 'bd dolt set':
--update-config Also write to config.yaml for team-wide defaults
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100 --update-config
bd dolt set data-dir /home/user/.beads-dolt/myproject
bd dolt test
```
bd dolt [flags]
```
## bd dolt clean-databases
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_*
These waste server memory and can degrade performance under concurrent load.
Use --dry-run to see what would be dropped without actually dropping.
```
bd dolt clean-databases [flags]
```
**Flags:**
```
--dry-run Show what would be dropped without dropping
```
## bd dolt commit
Create a Dolt commit from any uncommitted changes in the working set.
This is the primary commit point for batch mode. When auto-commit is set to
"batch", changes accumulate in the working set across multiple bd commands and
are committed together here with a descriptive summary message.
Also useful before push operations that require a clean working set, or when
auto-commit was off or changes were made externally.
For more options (--stdin, custom messages), see: bd vc commit
```
bd dolt commit [flags]
```
**Flags:**
```
-m, --message string Commit message (default: auto-generated)
```
## bd dolt killall
Find and kill orphan dolt sql-server processes not tracked by the
canonical PID file for the current repo's Dolt data directory.
Under an orchestrator, the canonical server lives at $GT_ROOT/.beads/. Any other
dolt sql-server processes using that shared data directory are considered
orphans and will be killed.
In standalone mode, only dolt sql-server processes using the current
project's Dolt data directory are eligible for cleanup. Other projects'
servers are preserved.
```
bd dolt killall [flags]
```
## bd dolt pull
Pull commits from the configured Dolt remote into the local database.
Requires a Dolt remote to be configured in the database directory.
For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment
variables for authentication.
Use --remote to pull from a specific named remote instead of the default.
The remote must already exist (see 'bd dolt remote add').
```
bd dolt pull [flags]
```
**Flags:**
```
--remote string Pull from a specific named remote instead of the default
```
## bd dolt push
Push local Dolt commits to the configured remote.
Requires a Dolt remote to be configured in the database directory.
For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment
variables for authentication.
Use --force to overwrite remote changes (e.g., when the remote has
uncommitted changes in its working set).
Use --remote to push to a specific named remote instead of the default.
The remote must already exist (see 'bd dolt remote add').
```
bd dolt push [flags]
```
**Flags:**
```
--force Force push (overwrite remote changes)
--remote string Push to a specific named remote instead of the default
```
## bd dolt remote
Manage Dolt remotes for push/pull replication.
Subcommands:
add &lt;name&gt; &lt;url&gt; Add a new remote
list List all configured remotes
remove &lt;name&gt; Remove a remote
```
bd dolt remote [flags]
```
### bd dolt remote add
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
```
bd dolt remote list [flags]
```
### bd dolt remote remove
Remove a Dolt remote
```
bd dolt remote remove <name> [flags]
```
## bd dolt set
Set a Dolt configuration value in metadata.json.
Keys:
database Database name (default: issue prefix or "beads")
host Server host (default: 127.0.0.1)
port Server port (auto-detected; override with bd dolt set port &lt;N&gt;)
user MySQL user (default: root)
data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
Use --update-config to also write to config.yaml for team-wide defaults.
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100
bd dolt set port 3307 --update-config
bd dolt set data-dir /home/user/.beads-dolt/myproject
```
bd dolt set <key> <value> [flags]
```
**Flags:**
```
--update-config Also write to config.yaml for team-wide defaults
```
## bd dolt show
Show current Dolt configuration with connection status
```
bd dolt show [flags]
```
## bd dolt start
Start a dolt sql-server for the current beads project.
The server runs in the background on a per-project port derived from the
project path. PID and logs are stored in .beads/.
The server auto-starts transparently when needed, so manual start is rarely
required. Use this command for explicit control or diagnostics.
```
bd dolt start [flags]
```
## bd dolt status
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.
```
bd dolt status [flags]
```
## bd dolt stop
Stop the dolt sql-server managed by beads for the current project.
This sends a graceful shutdown signal. The server will restart automatically
on the next bd command unless auto-start is disabled.
```
bd dolt stop [flags]
```
**Flags:**
```
--force Force stop the server
```
## bd dolt test
Test the connection to the configured Dolt server.
This verifies that:
1. The server is reachable at the configured host:port
2. The connection can be established
Use this before switching to server mode to ensure the server is running.
```
bd dolt test [flags]
```

View file

@ -0,0 +1,26 @@
---
title: "bd duplicate"
description: "Mark an issue as a duplicate of another"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc duplicate`.
Mark an issue as a duplicate of a canonical issue.
The duplicate issue is automatically closed with a reference to the canonical.
This is essential for large issue databases with many similar reports.
Examples:
bd duplicate bd-abc --of bd-xyz # Mark bd-abc as duplicate of bd-xyz
```
bd duplicate <id> --of <canonical> [flags]
```
**Flags:**
```
--of string Canonical issue ID (required)
```

View file

@ -0,0 +1,30 @@
---
title: "bd duplicates"
description: "Find and optionally merge duplicate issues"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc duplicates`.
Find issues with identical content (title, description, design, acceptance criteria).
Groups issues by content hash and reports duplicates with suggested merge targets.
The merge target is chosen by:
1. Reference count (most referenced issue wins)
2. Lexicographically smallest ID if reference counts are equal
Only groups issues with matching status (open with open, closed with closed).
Example:
bd duplicates # Show all duplicate groups
bd duplicates --auto-merge # Automatically merge all duplicates
bd duplicates --dry-run # Show what would be merged
```
bd duplicates [flags]
```
**Flags:**
```
--auto-merge Automatically merge all duplicates
--dry-run Show what would be merged without making changes
```

View file

@ -0,0 +1,33 @@
---
title: "bd edit"
description: "Edit an issue field in $EDITOR"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc edit`.
Edit an issue field using your configured $EDITOR.
By default, edits the description. Use flags to edit other fields.
Examples:
bd edit bd-42 # Edit description
bd edit bd-42 --title # Edit title
bd edit bd-42 --design # Edit design notes
bd edit bd-42 --notes # Edit notes
bd edit bd-42 --acceptance # Edit acceptance criteria
```
bd edit [id] [flags]
```
**Flags:**
```
--acceptance Edit the acceptance criteria
--description Edit the description (default)
--design Edit the design notes
--notes Edit the notes
--title Edit the title
```

View file

@ -0,0 +1,42 @@
---
title: "bd epic"
description: "Epic management commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc epic`.
Epic management commands
```
bd epic [flags]
```
## bd epic close-eligible
Close epics where all children are complete
```
bd epic close-eligible [flags]
```
**Flags:**
```
--dry-run Preview what would be closed without making changes
```
## bd epic status
Show epic completion status
```
bd epic status [flags]
```
**Flags:**
```
--eligible-only Show only epics eligible for closure
```

View file

@ -0,0 +1,49 @@
---
title: "bd export"
description: "Export issues to JSONL format"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc export`.
Export all issues to JSONL (newline-delimited JSON) format.
Each line is a complete JSON object representing one issue, including its
labels, dependencies, and comments.
This command is for issue export, migration, and interoperability. It exports
records from the issues table; it is not a full database backup and does not
capture Dolt branches, commit history, working-set state, or non-issue tables.
For supported full backup/restore flows, use 'bd backup init', 'bd backup sync',
and 'bd backup restore'.
By default, exports only regular issues (excluding infrastructure beads
like agents, roles, and messages). Use --all to include everything.
Memories (from 'bd remember') are excluded by default because they may
contain sensitive agent context. Use --include-memories or --all to
include them.
EXAMPLES:
bd export # Export issues to stdout
bd export -o issues.jsonl # Export issues to file
bd export --include-memories # Export issues + memories
bd export --all -o full.jsonl # Include infra + templates + gates + memories
bd export --scrub -o clean.jsonl # Exclude test/pollution records
```
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
```

View file

@ -0,0 +1,21 @@
---
title: "bd federation"
description: "Manage peer-to-peer federation (requires CGO)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc federation`.
Federation commands require CGO and the Dolt storage backend.
This binary was built without CGO support. To use federation features:
1. Use pre-built binaries from GitHub releases, or
2. Build from source with CGO enabled
Federation enables synchronized issue tracking across multiple workspaces,
each maintaining their own Dolt database while sharing updates via remotes.
```
bd federation [flags]
```

View file

@ -0,0 +1,50 @@
---
title: "bd find-duplicates"
description: "Find semantically similar issues using text analysis or AI"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc find-duplicates`.
Find issues that are semantically similar but not exact duplicates.
Unlike 'bd duplicates' which finds exact content matches, find-duplicates
uses text similarity or AI to find issues that discuss the same topic
with different wording.
Approaches:
mechanical Token-based text similarity (default, no API key needed)
ai LLM-based semantic comparison (requires ANTHROPIC_API_KEY or ai.api_key)
The mechanical approach tokenizes titles and descriptions, then computes
Jaccard similarity between all issue pairs. It's fast and free but may
miss semantically similar issues with very different wording.
The AI approach sends candidate pairs to Claude for semantic comparison.
It first uses mechanical pre-filtering to reduce the number of API calls,
then asks the LLM to judge whether the remaining pairs are true duplicates.
Examples:
bd find-duplicates # Mechanical similarity (default)
bd find-duplicates --threshold 0.4 # Lower threshold = more results
bd find-duplicates --method ai # Use AI for semantic comparison
bd find-duplicates --status open # Only check open issues
bd find-duplicates --limit 20 # Show top 20 pairs
bd find-duplicates --json # JSON output
```
bd find-duplicates [flags]
```
**Aliases:** find-dups
**Flags:**
```
-n, --limit int Maximum number of pairs to show (default 50)
--method string Detection method: mechanical, ai (default "mechanical")
--model string AI model to use (only with --method ai; default from config ai.model)
-s, --status string Filter by status (default: non-closed)
--threshold float Similarity threshold (0.0-1.0, lower = more results) (default 0.5)
```

View file

@ -0,0 +1,41 @@
---
title: "bd flatten"
description: "Squash all Dolt history into a single commit"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc flatten`.
Nuclear option: squash ALL Dolt commit history into a single commit.
This uses the Tim Sehn recipe:
1. Create a new branch from the current state
2. Soft-reset to the initial commit (preserving all data)
3. Commit everything as a single snapshot
4. Swap main branch to the new flattened branch
5. Run Dolt GC to reclaim space from old history
This is irreversible — all commit history is lost. The resulting database
has exactly one commit containing all current data.
Use this when:
- Your .beads/dolt directory has grown very large
- You don't need commit-level history (time travel)
- You want to start fresh with minimal storage
Examples:
bd flatten --dry-run # Preview: show commit count and disk usage
bd flatten --force # Actually squash all history
bd flatten --force --json # JSON output
```
bd flatten [flags]
```
**Flags:**
```
--dry-run Preview without making changes
-f, --force Confirm irreversible history squash
```

View file

@ -0,0 +1,20 @@
---
title: "bd forget"
description: "Remove a persistent memory"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc forget`.
Remove a memory by its key.
Use 'bd memories' to see available keys.
Examples:
bd forget dolt-phantoms
bd forget auth-jwt
```
bd forget <key> [flags]
```

View file

@ -0,0 +1,144 @@
---
title: "bd formula"
description: "Manage workflow formulas"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc formula`.
Manage workflow formulas - the source layer for molecule templates.
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
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
website/docs/workflows/formulas.md # narrative reference
```
bd formula [flags]
```
## bd formula convert
Convert formula files from JSON to TOML format.
TOML format provides better ergonomics:
- Multi-line strings without \n escaping
- Human-readable diffs
- Comments allowed
The convert command reads a .formula.json file and outputs .formula.toml.
The original JSON file is preserved (use --delete to remove it).
Examples:
bd formula convert shiny # Convert shiny.formula.json to .toml
bd formula convert ./my.formula.json # Convert specific file
bd formula convert --all # Convert all JSON formulas
bd formula convert shiny --delete # Convert and remove JSON file
bd formula convert shiny --stdout # Print TOML to stdout
```
bd formula convert <formula-name|path> [--all] [flags]
```
**Flags:**
```
--all Convert all JSON formulas
--delete Delete JSON file after conversion
--stdout Print TOML to stdout instead of file
```
## bd formula list
List all formulas from search paths.
Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
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
bd formula list --type workflow
bd formula list --type convoy
```
bd formula list [flags]
```
**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.
Displays:
- Formula metadata (name, type, description)
- Variables with defaults and constraints
- Steps with dependencies
- 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
bd formula show security-audit --json
```
bd formula show <formula-name> [flags]
```

204
docs/cli-reference/gate.md Normal file
View file

@ -0,0 +1,204 @@
---
title: "bd gate"
description: "Manage async coordination gates"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc gate`.
Gates are async wait conditions that block workflow steps.
Gates are created automatically when a formula step has a gate field.
They must be closed (manually or via watchers) for the blocked step to proceed.
Gate types:
human - Requires manual bd close (Phase 1)
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 cross-rig bead to close (Phase 4)
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
bd gate list --all # Show all gates including closed
bd gate check # Evaluate all open gates
bd gate check --type=bead # Evaluate only bead gates
bd gate resolve &lt;id&gt; # Close a gate manually
```
bd gate [flags]
```
## bd gate add-waiter
Register an agent as a waiter on a gate bead.
When the gate closes, the waiter will receive a wake notification via 'bd gate wake'.
The waiter is typically the worker's address (e.g., "my-project/workers/agent-1").
This is used by 'bd done --phase-complete' to register for gate wake notifications.
```
bd gate add-waiter <gate-id> <waiter> [flags]
```
## bd gate check
Evaluate gate conditions and automatically close resolved gates.
By default, checks all open gates. Use --type to filter by gate type.
Gate types:
gh - Check all GitHub gates (gh:run and gh:pr)
gh:run - Check GitHub Actions workflow runs
gh:pr - Check pull request merge status
timer - Check timer gates (auto-expire based on timeout)
bead - Check cross-rig bead gates
all - Check all gate types
GitHub gates use the 'gh' CLI to query status:
- gh:run checks 'gh run view &lt;id&gt; --json status,conclusion'
- gh:pr checks 'gh pr view &lt;id&gt; --json state,title'
A gate is resolved when:
- gh:run: status=completed AND conclusion=success
- gh:pr: state=MERGED
- timer: current time &gt; created_at + timeout
- bead: target bead status=closed
A gate is escalated when:
- gh:run: status=completed AND conclusion in (failure, canceled)
- gh:pr: state=CLOSED
Examples:
bd gate check # Check all gates
bd gate check --type=gh # Check only GitHub gates
bd gate check --type=gh:run # Check only workflow run gates
bd gate check --type=timer # Check only timer gates
bd gate check --type=bead # Check only cross-rig bead gates
bd gate check --dry-run # Show what would happen without changes
bd gate check --escalate # Escalate expired/failed gates
```
bd gate check [flags]
```
**Flags:**
```
--dry-run Show what would happen without making changes
-e, --escalate Escalate failed/expired gates
-l, --limit int Limit results (default 100) (default 100)
-t, --type string Gate type to check (gh, gh:run, gh:pr, timer, bead, all)
```
## bd gate create
Create an ad-hoc gate issue that blocks another issue until resolved.
The blocked issue will not appear in 'bd ready' until the gate is resolved
via 'bd gate resolve'.
Gate types:
human - Requires manual 'bd gate resolve' (default)
timer - Auto-resolves after --timeout duration
gh:run - Waits for GitHub Actions workflow
gh:pr - Waits for PR merge
Examples:
bd gate create --blocks bd-abc
bd gate create --type=human --blocks bd-abc --reason="Need design review"
bd gate create --type=timer --blocks bd-abc --timeout=2h
bd gate create --type=gh:pr --blocks bd-abc --await-id=42
```
bd gate create [flags]
```
**Flags:**
```
--await-id string Condition identifier (run ID, PR number, etc.)
--blocks string Issue ID to block (required)
-r, --reason string Reason for the gate
--timeout string Timeout duration (e.g., 2h, 30m)
-t, --type string Gate type (human, timer, gh:run, gh:pr) (default "human")
```
## bd gate discover
Discovers GitHub workflow run IDs for gates awaiting CI/CD completion.
This command finds open gates with await_type="gh:run" that don't have an await_id,
queries recent GitHub workflow runs, and matches them using heuristics:
- Branch name matching
- Commit SHA matching
- Time proximity (runs within 5 minutes of gate creation)
Once matched, the gate's await_id is updated with the GitHub run ID, enabling
subsequent polling to check the run's status.
Examples:
bd gate discover # Auto-discover run IDs for all matching gates
bd gate discover --dry-run # Preview what would be matched (no updates)
bd gate discover --branch main --limit 10 # Only match runs on 'main' branch
```
bd gate discover [flags]
```
**Flags:**
```
-b, --branch string Filter runs by branch (default: current branch)
-n, --dry-run Preview mode: show matches without updating
-l, --limit int Max runs to query from GitHub (default 10)
-a, --max-age duration Max age for gate/run matching (default 30m0s)
```
## bd gate list
List all gate issues in the current beads database.
By default, shows only open gates. Use --all to include closed gates.
```
bd gate list [flags]
```
**Flags:**
```
-a, --all Show all gates including closed
-n, --limit int Limit results (default 50) (default 50)
```
## bd gate resolve
Close a gate issue to unblock the step waiting on it.
This is equivalent to 'bd close &lt;gate-id&gt;' but with a more explicit name.
Use --reason to provide context for why the gate was resolved.
```
bd gate resolve <gate-id> [flags]
```
**Flags:**
```
-r, --reason string Reason for resolving the gate
```
## bd gate show
Display details of a gate issue including its waiters.
This is similar to 'bd show' but validates that the issue is a gate.
```
bd gate show <gate-id> [flags]
```

40
docs/cli-reference/gc.md Normal file
View file

@ -0,0 +1,40 @@
---
title: "bd gc"
description: "Garbage collect: decay old issues, compact Dolt commits, run Dolt GC"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc gc`.
Full lifecycle garbage collection for standalone Beads databases.
Runs three phases in sequence:
1. DECAY — Delete closed issues older than N days (default 90)
2. COMPACT — Squash old Dolt commits into fewer commits (bd compact)
3. GC — Run Dolt garbage collection to reclaim disk space
Each phase can be skipped individually. Use --dry-run to preview all phases
without making changes.
Examples:
bd gc # Full GC with defaults (90 day decay)
bd gc --dry-run # Preview what would happen
bd gc --older-than 30 # Decay issues closed 30+ days ago
bd gc --skip-decay # Skip issue deletion, just compact+GC
bd gc --skip-dolt # Skip Dolt GC, just decay+compact
bd gc --force # Skip confirmation prompt
```
bd gc [flags]
```
**Flags:**
```
--dry-run Preview without making changes
-f, --force Skip confirmation prompts
--older-than int Delete closed issues older than N days (default 90)
--skip-decay Skip issue deletion phase
--skip-dolt Skip Dolt garbage collection phase
```

View file

@ -0,0 +1,98 @@
---
title: "bd github"
description: "GitHub integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc github`.
Commands for syncing issues between beads and GitHub.
Configuration can be set via 'bd config' or environment variables:
github.token / GITHUB_TOKEN - Personal access token
github.owner / GITHUB_OWNER - Repository owner
github.repo / GITHUB_REPO - Repository name
github.repository / GITHUB_REPOSITORY - Combined "owner/repo" format
github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise)
```
bd github [flags]
```
## bd github pull
Pull one or more items from GitHub.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd github sync --pull-only --issues &lt;refs&gt;
```
bd github pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
## bd github push
Push one or more beads issues to GitHub.
Accepts bead IDs as positional arguments.
Equivalent to: bd github sync --push-only --issues &lt;ids&gt;
```
bd github push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd github repos
List GitHub repositories that the configured token has access to.
```
bd github repos [flags]
```
## bd github status
Display current GitHub configuration and sync status.
```
bd github status [flags]
```
## bd github sync
Synchronize issues between beads and GitHub.
By default, performs bidirectional sync:
- Pulls new/updated issues from GitHub to beads
- Pushes local beads issues to GitHub
Use --pull-only or --push-only to limit direction.
```
bd github sync [flags]
```
**Flags:**
```
--dry-run Show what would be synced without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-github On conflict, use GitHub version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--pull-only Only pull issues from GitHub
--push-only Only push issues to GitHub
```

View file

@ -0,0 +1,105 @@
---
title: "bd gitlab"
description: "GitLab integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc gitlab`.
Commands for syncing issues between beads and GitLab.
Configuration can be set via 'bd config' or environment variables:
gitlab.url / GITLAB_URL - GitLab instance URL
gitlab.token / GITLAB_TOKEN - Personal access token
gitlab.project_id / GITLAB_PROJECT_ID - Project ID or path
gitlab.group_id / GITLAB_GROUP_ID - Group ID for group-level sync
gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode
```
bd gitlab [flags]
```
## bd gitlab projects
List GitLab projects that the configured token has access to.
```
bd gitlab projects [flags]
```
## bd gitlab pull
Pull one or more items from GitLab.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd gitlab sync --pull-only --issues &lt;refs&gt;
```
bd gitlab pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
## bd gitlab push
Push one or more beads issues to GitLab.
Accepts bead IDs as positional arguments.
Equivalent to: bd gitlab sync --push-only --issues &lt;ids&gt;
```
bd gitlab push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd gitlab status
Display current GitLab configuration and sync status.
```
bd gitlab status [flags]
```
## bd gitlab sync
Synchronize issues between beads and GitLab.
By default, performs bidirectional sync:
- Pulls new/updated issues from GitLab to beads
- Pushes local beads issues to GitLab
Use --pull-only or --push-only to limit direction.
```
bd gitlab sync [flags]
```
**Flags:**
```
--assignee string Filter by assignee username
--dry-run Show what would be synced without making changes
--exclude-type string Exclude these issue types from sync (comma-separated)
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--label string Filter by labels (comma-separated, AND logic)
--milestone string Filter by milestone title
--no-ephemeral Exclude ephemeral/wisp issues from push (default: true) (default true)
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-gitlab On conflict, use GitLab version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--project string Filter to issues from this project ID (group mode)
--pull-only Only pull issues from GitLab
--push-only Only push issues to GitLab
--type string Only sync these issue types (comma-separated, e.g. 'epic,feature,task')
```

View file

@ -0,0 +1,61 @@
---
title: "bd graph"
description: "Display issue dependency graph"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc graph`.
Display a visualization of an issue's dependency graph.
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.
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
--box ASCII boxes showing layers, more detailed
--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
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
- Higher layers depend on lower layers
- Nodes in the same layer can run in parallel
Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred
Examples:
bd graph issue-id # Terminal DAG visualization (default)
bd graph --box issue-id # ASCII boxes with layer grouping
bd graph --dot issue-id | dot -Tsvg &gt; graph.svg # SVG via Graphviz
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 [issue-id] [flags]
```
**Flags:**
```
--all Show graph for all open issues
--box ASCII boxes showing layers
--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)
```
## bd graph check
Check the dependency graph for cycles, orphans, and other integrity issues.
Returns exit code 0 if the graph is clean, 1 if issues are found.
```
bd graph check [flags]
```

View file

@ -0,0 +1,31 @@
---
title: "bd heartbeat"
description: "Refresh the lease on an issue you hold in_progress"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc heartbeat`.
Refresh the lease on an issue you currently hold in_progress.
A claim carries a lease that expires after a TTL. A worker keeps its claim alive
by heartbeating faster than the TTL; once it stops (because it died), the lease
goes stale and 'bd reclaim' reverts the issue to ready so another worker can pick
it up. Heartbeat pushes lease_expires_at forward and stamps heartbeat_at = now.
Only the current owner may heartbeat. If the lease has already been reclaimed or
the issue closed, heartbeat fails so the worker learns to stop.
Heartbeat writes a Dolt commit, so heartbeat well below the TTL but not so fast
it bloats history — cadence should be a small fraction of the TTL, not per-op.
Examples:
bd heartbeat bd-123
bd hb bd-123
```
bd heartbeat <id> [flags]
```
**Aliases:** hb

View file

@ -0,0 +1,25 @@
---
title: "bd history"
description: "Show version history for an issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc history`.
Show the complete version history of an issue, including all commits
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 <id> [flags]
```
**Flags:**
```
--limit int Limit number of history entries (0 = all)
```

View file

@ -0,0 +1,88 @@
---
title: "bd hooks"
description: "Manage git hooks for beads integration"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc hooks`.
Install, uninstall, or list git hooks for beads integration.
The hooks provide:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics
```
bd hooks [flags]
```
## bd hooks install
Install git hooks for beads integration.
By default, hooks are installed to .git/hooks/ in the current repository.
Use --beads to install to .beads/hooks/ (recommended for Dolt backend).
Use --shared to install to a versioned directory (.beads-hooks/) that can be
committed to git and shared with team members.
Hooks use section markers to coexist with existing hooks — any user content
outside the markers is preserved across installs and upgrades.
Installed hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers (for orchestrator agents)
```
bd hooks install [flags]
```
**Flags:**
```
--beads Install hooks to .beads/hooks/ (recommended for Dolt backend)
--chain Chain with existing hooks (run them before bd hooks)
--force Overwrite existing hooks without backup
--shared Install hooks to .beads-hooks/ (versioned) instead of .git/hooks/
```
## bd hooks list
Show the status of bd git hooks (installed, outdated, missing).
```
bd hooks list [flags]
```
## bd hooks run
Execute the logic for a git hook. This command is typically called by
thin shim scripts installed in .git/hooks/.
Supported hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics
The thin shim pattern ensures hook logic is always in sync with the
installed bd version - upgrading bd automatically updates hook behavior.
```
bd hooks run <hook-name> [args...] [flags]
```
## bd hooks uninstall
Remove bd git hooks from .git/hooks/ directory.
```
bd hooks uninstall [flags]
```

100
docs/cli-reference/human.md Normal file
View file

@ -0,0 +1,100 @@
---
title: "bd human"
description: "Show essential commands for human users"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc human`.
Display a focused help menu showing only the most common commands.
bd has 70+ commands - many for AI agents, integrations, and advanced workflows.
This command shows the ~15 essential commands that human users need most often.
For the full command list, run: bd --help
SUBCOMMANDS:
human list List all human-needed beads (issues with 'human' label)
human respond &lt;id&gt; Respond to a human-needed bead (adds comment and closes)
human dismiss &lt;id&gt; Dismiss a human-needed bead permanently
human stats Show summary statistics for human-needed beads
```
bd human [flags]
```
## bd human dismiss
Dismiss a human-needed bead permanently without responding.
The issue is closed with a "Dismissed" reason and optional note.
Examples:
bd human dismiss bd-123
bd human dismiss bd-123 --reason "No longer applicable"
```
bd human dismiss <issue-id> [flags]
```
**Flags:**
```
--reason string Reason for dismissal (optional)
```
## bd human list
List all issues labeled with 'human' tag.
These are issues that require human intervention or input.
Examples:
bd human list
bd human list --status=open
bd human list --json
```
bd human list [flags]
```
**Flags:**
```
-s, --status string Filter by status (open, closed, etc.)
```
## bd human respond
Respond to a human-needed bead by adding a comment and closing it.
The response is added as a comment and the issue is closed with reason "Responded".
Examples:
bd human respond bd-123 --response "Use OAuth2 for authentication"
bd human respond bd-123 -r "Approved, proceed with implementation"
```
bd human respond <issue-id> [flags]
```
**Flags:**
```
-r, --response string Response text (required)
```
## bd human stats
Display summary statistics for human-needed beads.
Shows counts for total, pending (open), responded (closed without dismiss),
and dismissed beads.
Example:
bd human stats
```
bd human stats [flags]
```

View file

@ -0,0 +1,84 @@
---
title: "bd import"
description: "Import issues from a JSONL file or stdin into the database"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc import`.
Import issues from a JSONL file (newline-delimited JSON) into the database.
If no file is specified, imports from the configured import.path under .beads/
(default: issues.jsonl). Use "-" to read from stdin. This is the incremental counterpart to
'bd export': new issues are created and existing issues are updated (upsert
semantics).
Memory records (lines with "_type":"memory") are automatically detected and
imported as persistent memories (equivalent to 'bd remember'). This makes
'bd export | bd import' a full round-trip for both issues and memories.
Each JSONL line should map to an issue. The importer accepts every field
'bd export' emits — see 'bd export' output for the canonical schema. Only
"title" is required; everything else is optional.
Common fields:
title Required. Short summary.
description Long-form body.
design, notes, Additional content sections.
acceptance_criteria
issue_type bug | feature | task | epic | chore | ...
priority 0-4 (0 = critical). 0 is preserved (no omitempty).
status open | in_progress | blocked | closed | ...
(rows with status "tombstone" are skipped)
assignee, owner, Ownership metadata.
created_by
labels Array of strings.
dependencies Array of &#123;issue_id, depends_on_id, type, ...&#125;.
comments Array of comment objects.
external_ref, Cross-system identifiers (e.g. "gh-9").
source_system
due_at, defer_until RFC3339 timestamps for scheduling.
metadata Arbitrary JSON object preserved verbatim.
Timestamps (created_at, updated_at, started_at, closed_at) are preserved
when present in the JSONL and otherwise filled in by the importer. The
legacy "wisp" boolean is accepted as an alias for "ephemeral".
By default a row only rewrites an existing local issue when its
updated_at is strictly newer. Older rows are skipped (reported as
stale_skipped_ids) and rows with the same updated_at keep every local
column — updated_at has second granularity, so a timestamp tie can be
two distinct same-second updates, and the local row wins the tie
(reported as tie_kept_local_ids; the row's labels/comments/dependencies
still merge). The guard is also enforced inside the upsert itself, so a
local update that lands while the import is running is preserved rather
than overwritten. Existing issues that the import did rewrite are listed
with a field-level summary (updated_issues), so local state changed by
an import is visible. To deliberately restore an older snapshot, pass
--allow-stale, which imports every row even when it overwrites newer
local state.
EXAMPLES:
bd import # Import from configured import.path
bd import backup.jsonl # Import from a specific file
bd import -i backup.jsonl # Legacy alias for a specific file
bd import - # Read JSONL from stdin
cat issues.jsonl | bd import - # Pipe JSONL from another tool
bd import --dry-run # Show what would be imported
bd import --dedup # Skip issues with duplicate titles
bd import --allow-stale old.jsonl # Restore an older snapshot (overwrites newer local rows)
bd import --json # Structured output with created and skipped IDs
```
bd import [file|-] [flags]
```
**Flags:**
```
--allow-stale Import rows even when older than the local issue (required to restore an older snapshot)
--dedup Skip lines whose title matches an existing open issue
--dry-run Show what would be imported without importing
-i, --input string Read JSONL from a specific file
```

129
docs/cli-reference/index.md Normal file
View file

@ -0,0 +1,129 @@
---
title: CLI Reference
description: Generated reference for every bd command
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --docs-root`.
This reference covers all 112 live top-level `bd` commands. Regenerate it with:
```bash
./scripts/generate-cli-docs.sh
```
## Commands
- [`bd admin`](/cli-reference/admin)
- [`bd ado`](/cli-reference/ado)
- [`bd assign`](/cli-reference/assign)
- [`bd audit`](/cli-reference/audit)
- [`bd backup`](/cli-reference/backup)
- [`bd batch`](/cli-reference/batch)
- [`bd blocked`](/cli-reference/blocked)
- [`bd bootstrap`](/cli-reference/bootstrap)
- [`bd branch`](/cli-reference/branch)
- [`bd children`](/cli-reference/children)
- [`bd close`](/cli-reference/close)
- [`bd comment`](/cli-reference/comment)
- [`bd comments`](/cli-reference/comments)
- [`bd compact`](/cli-reference/compact)
- [`bd completion`](/cli-reference/completion)
- [`bd config`](/cli-reference/config)
- [`bd context`](/cli-reference/context)
- [`bd cook`](/cli-reference/cook)
- [`bd count`](/cli-reference/count)
- [`bd create`](/cli-reference/create)
- [`bd create-form`](/cli-reference/create-form)
- [`bd defer`](/cli-reference/defer)
- [`bd delete`](/cli-reference/delete)
- [`bd dep`](/cli-reference/dep)
- [`bd diff`](/cli-reference/diff)
- [`bd doctor`](/cli-reference/doctor)
- [`bd dolt`](/cli-reference/dolt)
- [`bd duplicate`](/cli-reference/duplicate)
- [`bd duplicates`](/cli-reference/duplicates)
- [`bd edit`](/cli-reference/edit)
- [`bd epic`](/cli-reference/epic)
- [`bd export`](/cli-reference/export)
- [`bd federation`](/cli-reference/federation)
- [`bd find-duplicates`](/cli-reference/find-duplicates)
- [`bd flatten`](/cli-reference/flatten)
- [`bd forget`](/cli-reference/forget)
- [`bd formula`](/cli-reference/formula)
- [`bd gate`](/cli-reference/gate)
- [`bd gc`](/cli-reference/gc)
- [`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)
- [`bd import`](/cli-reference/import)
- [`bd info`](/cli-reference/info)
- [`bd init`](/cli-reference/init)
- [`bd init-safety`](/cli-reference/init-safety)
- [`bd jira`](/cli-reference/jira)
- [`bd kv`](/cli-reference/kv)
- [`bd label`](/cli-reference/label)
- [`bd linear`](/cli-reference/linear)
- [`bd link`](/cli-reference/link)
- [`bd lint`](/cli-reference/lint)
- [`bd list`](/cli-reference/list)
- [`bd mail`](/cli-reference/mail)
- [`bd memories`](/cli-reference/memories)
- [`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)
- [`bd onboard`](/cli-reference/onboard)
- [`bd orphans`](/cli-reference/orphans)
- [`bd ping`](/cli-reference/ping)
- [`bd preflight`](/cli-reference/preflight)
- [`bd prime`](/cli-reference/prime)
- [`bd priority`](/cli-reference/priority)
- [`bd promote`](/cli-reference/promote)
- [`bd prune`](/cli-reference/prune)
- [`bd purge`](/cli-reference/purge)
- [`bd q`](/cli-reference/q)
- [`bd query`](/cli-reference/query)
- [`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)
- [`bd rename-prefix`](/cli-reference/rename-prefix)
- [`bd reopen`](/cli-reference/reopen)
- [`bd repo`](/cli-reference/repo)
- [`bd restore`](/cli-reference/restore)
- [`bd rules`](/cli-reference/rules)
- [`bd search`](/cli-reference/search)
- [`bd set-state`](/cli-reference/set-state)
- [`bd setup`](/cli-reference/setup)
- [`bd ship`](/cli-reference/ship)
- [`bd show`](/cli-reference/show)
- [`bd sql`](/cli-reference/sql)
- [`bd stale`](/cli-reference/stale)
- [`bd state`](/cli-reference/state)
- [`bd status`](/cli-reference/status)
- [`bd statuses`](/cli-reference/statuses)
- [`bd supersede`](/cli-reference/supersede)
- [`bd swarm`](/cli-reference/swarm)
- [`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)
- [`bd vc`](/cli-reference/vc)
- [`bd version`](/cli-reference/version)
- [`bd where`](/cli-reference/where)
- [`bd worktree`](/cli-reference/worktree)

View file

@ -0,0 +1,37 @@
---
title: "bd info"
description: "Show database information"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc info`.
Display information about the current database.
This command helps debug issues where bd is using an unexpected database. It shows:
- The absolute path to the database file
- Database statistics (issue count)
- Schema information (with --schema flag)
- What's new in recent versions (with --whats-new flag)
Examples:
bd info
bd info --json
bd info --schema --json
bd info --whats-new
bd info --whats-new --json
bd info --thanks
```
bd info [flags]
```
**Flags:**
```
--json Output in JSON format
--schema Include schema information in output
--thanks Show thank you page for contributors
--whats-new Show agent-relevant changes from recent versions
```

View file

@ -0,0 +1,80 @@
---
title: "bd init-safety"
description: "Explain bd init flag semantics and the destroy-token format"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc init-safety`.
bd init flag safety contract.
Every bd init invocation resolves project_id from exactly one explicitly
named source (local reinit, remote adoption, or a fresh mint). When the
source is ambiguous, bd init refuses.
FLAG SURFACE
bd init Mint a new identity. Bootstraps from
origin if it has refs/dolt/data.
bd init --reinit-local Re-initialize local .beads/ over existing
local data. Does NOT authorize discarding
remote history. If origin has Dolt data
this will refuse — pair with
--discard-remote to override.
bd init --reinit-local \ Discard the remote's Dolt history and
--discard-remote replace it with the local reinit. First
bd dolt push after this will be a
history-replacing force-push.
bd init --force Deprecated alias for --reinit-local.
Kept working for ≥2 releases.
bd init --from-jsonl Import from configured import.path. If
origin has Dolt data, this refuses unless
--discard-remote authorizes replacing that
remote history.
ADOPTING A REMOTE
If you want to use the remote's existing history, use:
bd bootstrap
bd init will automatically suggest this when a remote is detected.
DESTROY-TOKEN (non-interactive only)
When running with no TTY (CI, agents, piped input), --discard-remote
requires an explicit --destroy-token value. The token format is:
DESTROY-&lt;issue-prefix&gt;
For example, if your issue prefix is "bd", the token is "DESTROY-bd":
bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd
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
docs/adr/0002-init-safety-invariants.md).
EXIT CODES
10 refused: remote has Dolt history and you selected local history
without --discard-remote
11 refused: existing local data and you declined the destroy confirm
12 refused: --discard-remote passed without a valid --destroy-token
(non-interactive mode)
RECOVERY
If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery
playbooks for each exit code.
```
bd init-safety [flags]
```

101
docs/cli-reference/init.md Normal file
View file

@ -0,0 +1,101 @@
---
title: "bd init"
description: "Initialize bd in the current directory"
---
{/* AUTO-GENERATED: do not edit manually */}
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.
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/STORAGE-BACKENDS.md for the trade-offs and setup.
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)
has already created the database.
With --stealth: configures per-repository git settings for invisible beads usage:
• .git/info/exclude to prevent beads files from being committed
Perfect for personal use without affecting repo collaborators.
To set up a specific AI tool, run: bd setup &lt;claude|cursor|aider|...&gt; --stealth
By default, beads uses an embedded Dolt engine (no external server needed).
Pass --server to use an external dolt sql-server instead. In server mode,
set connection details with --server-host, --server-port, and --server-user.
Password should be set via BEADS_DOLT_PASSWORD environment variable.
Auto-export is optional. When enabled, bd exports issues to
.beads/issues.jsonl after write commands (throttled to once per 60s). This is
for viewers (bv), interchange, and issue-level migration; not backup.
Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export.
To enable: bd config set export.auto true
Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
Skips all interactive prompts, using sensible defaults:
• Role defaults to "maintainer" (override with --role)
• Fork exclude auto-configured when fork detected
• Auto-export left at default (disabled)
• --contributor and --team flags are rejected (wizards require interaction)
Also auto-detected when stdin is not a terminal or CI=true is set.
```
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/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/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-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>/proxieddb/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>/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/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
```

120
docs/cli-reference/jira.md Normal file
View file

@ -0,0 +1,120 @@
---
title: "bd jira"
description: "Jira integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc jira`.
Synchronize issues between beads and Jira.
Configuration:
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set jira.projects "PROJ1,PROJ2" # Multiple projects
bd config set jira.api_token "YOUR_TOKEN"
bd config set jira.username "your_email@company.com" # For Jira Cloud
bd config set jira.push_prefix "hippo" # Only push hippo-* issues to Jira
bd config set jira.push_prefix "proj1,proj2" # Multiple prefixes (comma-separated)
Environment variables (alternative to config):
JIRA_API_TOKEN - Jira API token
JIRA_USERNAME - Jira username/email
JIRA_PROJECTS - Comma-separated project keys
Examples:
bd jira sync --pull # Import issues from Jira
bd jira sync --push # Export issues to Jira
bd jira sync # Bidirectional sync (pull then push)
bd jira sync --dry-run # Preview sync without changes
bd jira status # Show sync status
```
bd jira [flags]
```
## bd jira pull
Pull one or more items from Jira.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd jira sync --pull --issues &lt;refs&gt;
```
bd jira pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
## bd jira push
Push one or more beads issues to Jira.
Accepts bead IDs as positional arguments.
Equivalent to: bd jira sync --push --issues &lt;ids&gt;
```
bd jira push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd jira status
Show the current Jira sync status, including:
- Last sync timestamp
- Configuration status
- Number of issues with Jira links
- Issues pending push (no external_ref)
```
bd jira status [flags]
```
## bd jira sync
Synchronize issues between beads and Jira.
Modes:
--pull Import issues from Jira into beads
--push Export issues from beads to Jira
(no flags) Bidirectional sync: pull then push, with conflict resolution
Conflict Resolution:
By default, newer timestamp wins. Override with:
--prefer-local Always prefer local beads version
--prefer-jira Always prefer Jira version
Examples:
bd jira sync --pull # Import from Jira
bd jira sync --push --create-only # Push new issues only
bd jira sync --dry-run # Preview without changes
bd jira sync --prefer-local # Bidirectional, local wins
```
bd jira sync [flags]
```
**Flags:**
```
--create-only Only create new issues, don't update existing
--dry-run Preview sync without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-jira Prefer Jira version on conflicts
--prefer-local Prefer local version on conflicts
--project strings Project key(s) to sync (overrides configured project/projects)
--pull Pull issues from Jira
--push Push issues to Jira
--state string Issue state to sync: open, closed, all (default "all")
```

75
docs/cli-reference/kv.md Normal file
View file

@ -0,0 +1,75 @@
---
title: "bd kv"
description: "Key-value store commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc kv`.
Commands for working with the beads key-value store.
The key-value store is useful for storing flags, environment variables,
or other user-defined data that persists across sessions.
Examples:
bd kv set mykey myvalue # Set a value
bd kv get mykey # Get a value
bd kv clear mykey # Delete a key
bd kv list # List all key-value pairs
```
bd kv [flags]
```
## bd kv clear
Delete a key from the beads key-value store.
Examples:
bd kv clear feature_flag
bd kv clear api_endpoint
```
bd kv clear <key> [flags]
```
## bd kv get
Get a value from the beads key-value store.
Examples:
bd kv get feature_flag
bd kv get api_endpoint
```
bd kv get <key> [flags]
```
## bd kv list
List all key-value pairs in the beads key-value store.
Examples:
bd kv list
bd kv list --json
```
bd kv list [flags]
```
## bd kv set
Set a key-value pair in the beads key-value store.
This is useful for storing flags, environment variables, or other
user-defined data that persists across sessions.
Examples:
bd kv set feature_flag true
bd kv set api_endpoint https://api.example.com
bd kv set max_retries 3
```
bd kv set <key> <value> [flags]
```

View file

@ -0,0 +1,54 @@
---
title: "bd label"
description: "Manage issue labels"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc label`.
Manage issue labels
```
bd label [flags]
```
## bd label add
Add a label to one or more issues
```
bd label add [issue-id...] [label] [flags]
```
## bd label list
List labels for an issue
```
bd label list [issue-id] [flags]
```
## bd label list-all
List all unique labels in the database
```
bd label list-all [flags]
```
## bd label propagate
Push a label from a parent down to all direct children that don't already have it. Useful for applying branch: labels across an epic's subtasks.
```
bd label propagate [parent-id] [label] [flags]
```
## bd label remove
Remove a label from one or more issues
```
bd label remove [issue-id...] [label] [flags]
```

View file

@ -0,0 +1,223 @@
---
title: "bd linear"
description: "Linear integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc linear`.
Synchronize issues between beads and Linear.
Configuration:
bd config set linear.api_key "YOUR_API_KEY"
bd config set linear.team_id "TEAM_ID"
bd config set linear.team_ids "TEAM_ID1,TEAM_ID2" # Multiple teams (comma-separated)
bd config set linear.project_id "PROJECT_ID" # Optional: sync only this project
Environment variables (alternative to config):
LINEAR_API_KEY - Linear API key (for individual developers)
LINEAR_TEAM_ID - Linear team ID (UUID, singular)
LINEAR_TEAM_IDS - Linear team IDs (comma-separated UUIDs)
OAuth (for CI workers / automated sync):
LINEAR_OAUTH_CLIENT_ID - OAuth app client ID
LINEAR_OAUTH_CLIENT_SECRET - OAuth app client secret
When both OAuth env vars are set, OAuth client_credentials flow is used
instead of the API key. This allows CI workers to authenticate as an
application (actor=application) rather than impersonating a user.
Precedence: OAuth &gt; LINEAR_API_KEY &gt; config file.
Data Mapping (optional, sensible defaults provided):
Priority mapping (Linear 0-4 to Beads 0-4):
bd config set linear.priority_map.0 4 # No priority -&gt; Backlog
bd config set linear.priority_map.1 0 # Urgent -&gt; Critical
bd config set linear.priority_map.2 1 # High -&gt; High
bd config set linear.priority_map.3 2 # Medium -&gt; Medium
bd config set linear.priority_map.4 3 # Low -&gt; Low
State mapping (Linear state type to Beads status):
bd config set linear.state_map.backlog open
bd config set linear.state_map.unstarted open
bd config set linear.state_map.started in_progress
bd config set linear.state_map.completed closed
bd config set linear.state_map.canceled closed
bd config set linear.state_map.my_custom_state in_progress # Custom state names
Label to issue type mapping:
bd config set linear.label_type_map.bug bug
bd config set linear.label_type_map.feature feature
bd config set linear.label_type_map.epic epic
Relation type mapping (Linear relations to Beads dependencies):
bd config set linear.relation_map.blocks blocks
bd config set linear.relation_map.blockedBy blocks
bd config set linear.relation_map.duplicate duplicates
bd config set linear.relation_map.related related
ID generation (optional, hash IDs to match bd/Jira hash mode):
bd config set linear.id_mode "hash" # hash (default)
bd config set linear.hash_length "6" # hash length 3-8 (default: 6)
Examples:
bd linear sync --pull # Import issues from Linear
bd linear sync --push # Export issues to Linear
bd linear sync # Bidirectional sync (pull then push)
bd linear sync --dry-run # Preview sync without changes
bd create "Fix login" --external-ref https://linear.app/team/issue/TEAM-123
# Link a local issue to an existing Linear issue
bd linear status # Show sync status
```
bd linear [flags]
```
## bd linear pull
Pull one or more items from Linear.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd linear sync --pull --issues &lt;refs&gt;
```
bd linear pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
--relations Import Linear relations as bd dependencies when pulling
```
## bd linear push
Push one or more beads issues to Linear.
Accepts bead IDs as positional arguments.
Equivalent to: bd linear sync --push --issues &lt;ids&gt;
```
bd linear push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd linear status
Show the current Linear sync status, including:
- Last sync timestamp
- Configuration status
- Number of issues with Linear links
- Issues pending push (no external_ref)
```
bd linear status [flags]
```
## bd linear sync
Synchronize issues between beads and Linear.
Modes:
--pull Import issues from Linear into beads
--push Export issues from beads to Linear
--pull-if-stale Pull only if data is stale (skip if fresh)
(no flags) Bidirectional sync: pull then push, with conflict resolution
Staleness (--pull-if-stale):
--threshold 20m How old data must be before pulling (default 20m)
A 5-minute debounce prevents agent loops: if a pull completed within 5 minutes,
data is always treated as fresh regardless of the threshold.
Team Selection:
--team ID1,ID2 Override configured team IDs for this sync
Multiple teams can be configured via linear.team_ids (comma-separated).
Falls back to linear.team_id for backward compatibility.
Push requires explicit --team when multiple teams are configured.
Pull Options:
--milestones Reconstruct Linear project milestones as local epic parents
Type Filtering (--push only):
--type task,feature Only sync issues of these types
--exclude-type wisp Exclude issues of these types
--include-ephemeral Include ephemeral issues (wisps, etc.); default is to exclude
--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
--prefer-linear Always prefer Linear version
Examples:
bd linear sync --pull # Import from Linear
bd linear sync --pull-if-stale # Pull only if data is stale
bd linear sync --pull-if-stale --threshold 5m # Pull if older than 5 minutes
bd linear sync --pull --relations # Import Linear blocking relations as bd deps
bd linear sync --push --create-only # Push new issues only
bd linear sync --push --type=task,feature # Push only tasks and features
bd linear sync --push --exclude-type=wisp # Push all except wisps
bd linear sync --push --parent=bd-abc123 # Push one ticket tree
bd linear sync --dry-run # Preview without changes
bd linear sync --prefer-local # Bidirectional, local wins
```
bd linear sync [flags]
```
**Flags:**
```
--create-only Only create new issues, don't update existing
--dry-run Preview sync without making changes
--exclude-type strings Exclude issues of these types (can be repeated)
--include-ephemeral Include ephemeral issues (wisps, etc.) when pushing to Linear
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--milestones Reconstruct Linear project milestones as local epic parents when pulling
--no-wait Fail immediately if another sync is running instead of waiting
--parent string Limit push to this beads ticket and its descendants
--prefer-linear Prefer Linear version on conflicts
--prefer-local Prefer local version on conflicts
--pull Pull issues from Linear
--pull-if-stale Pull only if Linear data is stale (skip if fresh)
--push Push issues to Linear
--relations Import Linear relations as bd dependencies when pulling
--state string Issue state to sync: open, closed, all (default "all")
--team strings Team ID(s) to sync (overrides configured team_id/team_ids)
--threshold duration Staleness threshold for --pull-if-stale (default 20m) (default 20m0s)
--type strings Only sync issues of these types (can be repeated)
--update-refs Update external_ref after creating Linear issues (default true)
```
## bd linear teams
List all teams accessible with your Linear API key.
Use this to find the team ID (UUID) needed for configuration.
Example:
bd linear teams
bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"
```
bd linear teams [flags]
```

View file

@ -0,0 +1,28 @@
---
title: "bd link"
description: "Link two issues with a dependency"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc link`.
Link two issues with a dependency.
Shorthand for 'bd dep add &lt;id1&gt; &lt;id2&gt;'. By default creates a "blocks"
dependency (id2 blocks id1). Use --type to specify a different relationship.
Examples:
bd link bd-123 bd-456 # bd-456 blocks bd-123
bd link bd-123 bd-456 --type related # bd-123 related to bd-456
bd link bd-123 bd-456 --type parent-child
```
bd link <id1> <id2> [flags]
```
**Flags:**
```
-t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from) (default "blocks")
```

View file

@ -0,0 +1,38 @@
---
title: "bd lint"
description: "Check issues for missing template sections"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc lint`.
Check issues for missing recommended sections based on issue type.
By default, lints all open issues. Specify issue IDs to lint specific issues.
Section requirements by type:
bug: Steps to Reproduce, Acceptance Criteria
task: Acceptance Criteria
feature: Acceptance Criteria
epic: Success Criteria
chore: (none)
Examples:
bd lint # Lint all open issues
bd lint bd-abc # Lint specific issue
bd lint bd-abc bd-def # Lint multiple issues
bd lint --type bug # Lint only bugs
bd lint --status all # Lint all issues (including closed)
```
bd lint [issue-id...] [flags]
```
**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)
```

View file

@ -0,0 +1,77 @@
---
title: "bd list"
description: "List issues"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc list`.
List issues
```
bd list [flags]
```
**Flags:**
```
--all Show all issues including closed (overrides default filter)
-a, --assignee string Filter by assignee
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow)
--defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow)
--deferred Show only issues with defer_until set
--desc-contains string Filter by description substring (case-insensitive)
--due-after string Filter issues due after date (supports relative: +6h, tomorrow)
--due-before string Filter issues due before date (supports relative: +6h, tomorrow)
--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)
--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
--id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)
--include-gates Include gate issues in output (normally hidden)
--include-infra Include infrastructure beads (agent/role/message) in output
--include-templates Include template molecules in output
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
--label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)
--label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)')
-n, --limit int Limit results (default 50, use 0 for unlimited) (default 50)
--long Show detailed multi-line output for each issue
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
--mol-type string Filter by molecule type: swarm, patrol, or work
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--no-pager Disable pager output
--no-parent Exclude child issues (show only top-level issues)
--no-pinned Exclude pinned issues
--notes-contains string Filter by notes substring (case-insensitive)
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
--overdue Show only issues with due_at in the past (not closed)
--parent string Filter by parent issue ID (shows children of specified issue)
--pinned Show only pinned issues
--pretty Display issues in a tree format with status/priority symbols
-p, --priority string Priority (0-4 or P0-P4, 0=highest)
--priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4)
--priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4)
--ready Show only ready issues (no active blockers, same semantics as bd ready)
-r, --reverse Reverse sort order
--skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels.
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
--spec string Filter by spec_id prefix
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters.
--title string Filter by title text (case-insensitive substring match)
--title-contains string Filter by title substring (case-insensitive)
--tree Hierarchical tree format (default: true; use --flat to disable) (default true)
-t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
-w, --watch Watch for changes and auto-update display (implies --pretty)
--wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation
```

View file

@ -0,0 +1,33 @@
---
title: "bd mail"
description: "Delegate to mail provider (e.g., gt mail)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc mail`.
Delegates mail operations to an external mail provider.
Agents often type 'bd mail' when working with beads, but mail functionality
is typically provided by the orchestrator. This command bridges that gap
by delegating to the configured mail provider.
Configuration (checked in order):
1. BEADS_MAIL_DELEGATE or BD_MAIL_DELEGATE environment variable
2. 'mail.delegate' config setting (bd config set mail.delegate "gt mail")
Examples:
# Configure delegation (one-time setup)
export BEADS_MAIL_DELEGATE="gt mail"
# or
bd config set mail.delegate "gt mail"
# Then use bd mail as if it were gt mail
bd mail inbox # Lists inbox
bd mail send mayor/ -s "Hi" # Sends mail
bd mail read msg-123 # Reads a message
```
bd mail [subcommand] [args...] [flags]
```

View file

@ -0,0 +1,19 @@
---
title: "bd memories"
description: "List or search persistent memories"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc memories`.
List all memories, or search by keyword.
Examples:
bd memories # list all memories
bd memories dolt # search for memories about dolt
bd memories "race flag" # search for a phrase
```
bd memories [search] [flags]
```

View file

@ -0,0 +1,96 @@
---
title: "bd merge-slot"
description: "Manage merge-slot gates for serialized conflict resolution"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc merge-slot`.
Merge-slot gates serialize conflict resolution in the merge queue.
A merge slot is an exclusive access primitive: only one agent can hold it at a time.
This prevents "monkey knife fights" where multiple polecats race to resolve conflicts
and create cascading conflicts.
Each rig has one merge slot bead: &lt;prefix&gt;-merge-slot (labeled gt:slot).
The slot uses:
- status=open: slot is available
- status=in_progress: slot is held
- metadata.holder: who currently holds the slot
- metadata.waiters: priority-ordered queue of waiters
Examples:
bd merge-slot create # Create merge slot for current rig
bd merge-slot check # Check if slot is available
bd merge-slot acquire # Try to acquire the slot
bd merge-slot release # Release the slot
```
bd merge-slot [flags]
```
## bd merge-slot acquire
Attempt to acquire the merge slot for exclusive access.
If the slot is available (status=open), it will be acquired:
- status set to in_progress
- holder set to the requester
If the slot is held (status=in_progress), the command fails unless
--wait is passed, which adds the requester to the waiters queue.
Use --holder to specify who is acquiring (default: BEADS_ACTOR env var).
```
bd merge-slot acquire [flags]
```
**Flags:**
```
--holder string Who is acquiring the slot (default: BEADS_ACTOR)
--wait Add to waiters list if slot is held
```
## bd merge-slot check
Check if the merge slot is available or held.
Returns:
- available: slot can be acquired
- held by &lt;holder&gt;: slot is currently held
- not found: no merge slot exists for this rig
```
bd merge-slot check [flags]
```
## bd merge-slot create
Create a merge slot bead for serialized conflict resolution.
The slot ID is automatically generated based on the beads prefix (e.g., gt-merge-slot).
The slot is created with status=open (available).
```
bd merge-slot create [flags]
```
## bd merge-slot release
Release the merge slot after conflict resolution is complete.
Sets status back to open and clears the holder field.
If there are waiters, the highest-priority waiter should then acquire.
```
bd merge-slot release [flags]
```
**Flags:**
```
--holder string Who is releasing the slot (for verification)
```

View file

@ -0,0 +1,49 @@
---
title: "bd metrics"
description: "Show or change anonymous usage-metrics settings"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc metrics`.
Show whether anonymous usage metrics are on, see exactly what is sent, and
turn them on or off.
bd shares anonymous usage metrics to learn how people actually use it — just
which commands get run, plus the bd version and OS platform. That's how we decide
what to polish next. We never collect your issues, paths, remotes, identity, or
any user-supplied text.
bd metrics show the current status and what is collected
bd metrics on turn metrics on
bd metrics off turn metrics off
bd metrics example show real examples of the events bd sends
```
bd metrics [flags]
```
## bd metrics example
Show real examples of the anonymous metrics bd sends
```
bd metrics example [flags]
```
## bd metrics off
Turn anonymous usage metrics off
```
bd metrics off [flags]
```
## bd metrics on
Turn anonymous usage metrics on
```
bd metrics on [flags]
```

View file

@ -0,0 +1,33 @@
---
title: "bd migrate-personal"
description: "Move personal planning issues from the project database to your planning repo"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc migrate-personal`.
Identify issues you created in the project database and move them to your
personal planning repository (~/.beads-planning by default).
This is a one-time migration for contributors who created personal planning
issues before contributor routing was configured.
The command:
1. Finds all issues in the project database created by your git identity
2. Shows you the list and asks for confirmation
3. Moves them to the planning repo configured in routing.contributor
EXAMPLES:
bd migrate-personal # Interactive: show list and prompt
bd migrate-personal -y # Non-interactive: skip confirmation
```
bd migrate-personal [flags]
```
**Flags:**
```
-y, --yes Skip confirmation prompt
```

View file

@ -0,0 +1,156 @@
---
title: "bd migrate"
description: "Database migration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc migrate`.
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
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.
```
bd migrate [flags]
```
**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 hooks
Analyze git hook files and sidecar artifacts for migration to marker-managed format.
Modes:
--dry-run Preview migration operations without changing files
--apply Apply migration operations
Examples:
bd migrate hooks --dry-run
bd migrate hooks --apply
bd migrate hooks --apply --yes
bd migrate hooks --dry-run --json
```
bd migrate hooks [path] [flags]
```
**Flags:**
```
--apply Apply planned hook migration changes
--dry-run Show what would be done without making changes
--json Output in JSON format
--yes Skip confirmation prompt for --apply
```
## bd migrate issues
Move issues from one source repository to another with filtering and dependency preservation.
This command updates the source_repo field for selected issues, allowing you to:
- Move contributor planning issues to upstream repository
- Reorganize issues across multi-phase repositories
- Consolidate issues from multiple repos
Examples:
# Preview migration from planning repo to current repo
bd migrate-issues --from ~/.beads-planning --to . --dry-run
# Move all open P1 bugs
bd migrate-issues --from ~/repo1 --to ~/repo2 --priority 1 --type bug --status open
# Move specific issues with their dependencies
bd migrate-issues --from . --to ~/archive --id bd-abc --id bd-xyz --include closure
# Move issues with label filter
bd migrate-issues --from . --to ~/feature-work --label frontend --label urgent
```
bd migrate issues [flags]
```
**Flags:**
```
--dry-run Show plan without making changes
--from string Source repository (required)
--id strings Specific issue IDs to migrate (can specify multiple)
--ids-file string File containing issue IDs (one per line)
--include string Include dependencies: none/upstream/downstream/closure (default "none")
--label strings Filter by labels (can specify multiple)
--priority int Filter by priority (0-4) (default -1)
--status string Filter by status (open/closed/all)
--strict Fail on orphaned dependencies or missing repos
--to string Destination repository (required)
--type string Filter by issue type (bug/feature/task/epic/chore/decision)
--within-from-only Only include dependencies from source repo (default true)
--yes Skip confirmation prompt
```
## bd migrate schema
Apply pending schema migrations idempotently.
Schema migrations also run automatically on store open, so this subcommand
is typically a no-op. It exists to make migration explicit and observable
in CI, release gates, and recovery scenarios.
Example:
bd migrate schema
bd migrate schema --json
```
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
```
## bd migrate sync
Configure separate branch workflow for multi-clone setups.
This sets the sync.branch config value so that issue data is committed
to a dedicated branch, keeping your main branch clean.
Example:
bd migrate sync beads-sync
```
bd migrate sync <branch> [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--json Output in JSON format
```

616
docs/cli-reference/mol.md Normal file
View file

@ -0,0 +1,616 @@
---
title: "bd mol"
description: "Molecule commands (work templates)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc mol`.
Manage molecules - work templates for agent workflows.
Protos are template epics with the "template" label. They define a DAG of work
that can be spawned to create real issues (molecules).
The molecule metaphor:
- A proto is an uninstantiated template (reusable work pattern)
- Spawning creates a molecule (real issues) from the proto
- Variables (&#123;&#123;key&#125;&#125;) are substituted during spawning
- Bonding combines protos or molecules into compounds
- Distilling extracts a proto from an ad-hoc epic
Commands:
show Show proto/molecule structure and variables
pour Instantiate proto as persistent mol (liquid phase)
wisp Instantiate proto as ephemeral wisp (vapor phase)
bond Polymorphic combine: proto+proto, proto+mol, mol+mol
squash Condense molecule to digest
burn Discard wisp
distill Extract proto from ad-hoc epic
Use "bd formula list" to list available formulas.
```
bd mol [flags]
```
**Aliases:** protomolecule
## bd mol bond
Bond two protos or molecules to create a compound.
The bond command is polymorphic - it handles different operand types:
formula + formula → cook both, compound proto
formula + proto → cook formula, compound proto
formula + mol → cook formula, spawn and attach
proto + proto → compound proto (reusable template)
proto + mol → spawn proto, attach to molecule
mol + proto → spawn proto, attach to molecule
mol + mol → join into compound molecule
Formula names (e.g., mol-polecat-arm) are cooked inline as ephemeral protos.
This avoids needing pre-cooked proto beads in the database.
Bond types:
sequential (default) - B runs after A completes
parallel - B runs alongside A
conditional - B runs only if A fails
Phase control:
By default, spawned protos follow the target's phase:
- Attaching to mol (Ephemeral=false) → spawns as persistent (Ephemeral=false)
- Attaching to ephemeral issue (Ephemeral=true) → spawns as ephemeral (Ephemeral=true)
Override with:
--pour Force spawn as liquid (persistent, Ephemeral=false)
--ephemeral Force spawn as vapor (ephemeral, Ephemeral=true, excluded from Dolt sync via dolt_ignore)
Dynamic bonding (Christmas Ornament pattern):
Use --ref to specify a custom child reference with variable substitution.
This creates IDs like "parent.child-ref" instead of random hashes.
Example:
bd mol bond mol-worker-arm bd-patrol --ref arm-&#123;&#123;worker_name&#125;&#125; --var worker_name=ace
# Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture)
Use cases:
- Found important bug during patrol? Use --pour to persist it
- Need ephemeral diagnostic on persistent feature? Use --ephemeral
- Spawning per-worker arms on a patrol? Use --ref for readable IDs
Examples:
bd mol bond mol-feature mol-deploy # Compound proto
bd mol bond mol-feature mol-deploy --type parallel # Run in parallel
bd mol bond mol-feature bd-abc123 # Attach proto to molecule
bd mol bond bd-abc123 bd-def456 # Join two molecules
bd mol bond mol-critical-bug wisp-patrol --pour # Persist found bug
bd mol bond mol-temp-check bd-feature --ephemeral # Ephemeral diagnostic
bd mol bond mol-arm bd-patrol --ref arm-&#123;&#123;name&#125;&#125; --var name=ace # Dynamic child ID
```
bd mol bond <A> <B> [flags]
```
**Aliases:** fart
**Flags:**
```
--as string Custom title for compound proto (proto+proto only)
--dry-run Preview what would be created
--ephemeral Force spawn as vapor (ephemeral, Ephemeral=true)
--pour Force spawn as liquid (persistent, Ephemeral=false)
--ref string Custom child reference with {{var}} substitution (e.g., arm-{{polecat_name}})
--type string Bond type: sequential, parallel, or conditional (default "sequential")
--var stringArray Variable substitution for spawned protos (key=value)
```
## bd mol burn
Burn a molecule, deleting it without creating a digest.
Unlike squash (which creates a permanent digest before deletion), burn
completely removes the molecule with no trace. Use this for:
- Abandoned patrol cycles
- Crashed or failed workflows
- Test/debug molecules you don't want to preserve
The burn operation differs based on molecule phase:
- Wisp (ephemeral): Direct delete
- Mol (persistent): Cascade delete (syncs to remotes)
CAUTION: This is a destructive operation. The molecule's data will be
permanently lost. If you want to preserve a summary, use 'bd mol squash'.
Example:
bd mol burn bd-abc123 # Delete molecule with no trace
bd mol burn bd-abc123 --dry-run # Preview what would be deleted
bd mol burn bd-abc123 --force # Skip confirmation
bd mol burn bd-a1 bd-b2 bd-c3 # Batch delete multiple wisps
```
bd mol burn <molecule-id> [molecule-id...] [flags]
```
**Flags:**
```
--dry-run Preview what would be deleted
--force Skip confirmation prompt
```
## bd mol current
Show where you are in a molecule workflow.
If molecule-id is given, show status for that molecule.
If not given, infer from in_progress issues assigned to current agent.
The output shows all steps with status indicators:
[done] - Step is complete (closed)
[current] - Step is in_progress (you are here)
[ready] - Step is ready to start (unblocked)
[blocked] - Step is blocked by dependencies
[pending] - Step is waiting
For large molecules (&gt;100 steps), a summary is shown instead.
Use --limit or --range to view specific steps:
bd mol current &lt;id&gt; --limit 50 # Show first 50 steps
bd mol current &lt;id&gt; --range 100-150 # Show steps 100-150
```
bd mol current [molecule-id] [flags]
```
**Flags:**
```
--for string Show molecules for a specific agent/assignee
--limit int Maximum number of steps to display (0 = auto, use 'all' threshold)
--range string Display specific step range (e.g., '1-50', '100-150')
```
## bd mol distill
Distill a molecule by extracting a reusable formula from an existing epic.
This is the reverse of pour: instead of formula → molecule, it's molecule → formula.
The distill command:
1. Loads the existing epic and all its children
2. Converts the structure to a .formula.json file
3. Replaces concrete values with &#123;&#123;variable&#125;&#125; placeholders (via --var flags)
Use cases:
- Team develops good workflow organically, wants to reuse it
- Capture tribal knowledge as executable templates
- Create starting point for similar future work
Variable syntax (both work - we detect which side is the concrete value):
--var branch=feature-auth Spawn-style: variable=value (recommended)
--var feature-auth=branch Substitution-style: value=variable
Output locations (first writable wins):
1. &lt;resolved-beads-dir&gt;/formulas/ (project-level, default)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user-level, if project not writable)
Examples:
bd mol distill bd-o5xe my-workflow
bd mol distill bd-abc release-workflow --var feature_name=auth-refactor
```
bd mol distill <epic-id> [formula-name] [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--output string Output directory for formula file
--var stringArray Replace value with {{variable}} placeholder (variable=value)
```
## bd mol last-activity
Show the most recent activity timestamp for a molecule.
Returns the timestamp of the most recent change to any step in the molecule,
making it easy to detect stale or stuck molecules.
Activity sources:
step_closed - A step was closed
step_updated - A step was updated (claimed, edited, etc.)
molecule_updated - The molecule root itself was updated
Examples:
bd mol last-activity hq-wisp-0laki
bd mol last-activity hq-wisp-0laki --json
```
bd mol last-activity <molecule-id> [flags]
```
## bd mol pour
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 lives in .beads/ (permanent storage) and is synced with git.
Phase transition: Proto (solid) -&gt; pour -&gt; Mol (liquid)
WHEN TO USE POUR vs WISP:
pour (liquid): Persistent work that needs audit trail
- Feature implementations spanning multiple sessions
- Work you may need to reference later
- Anything worth preserving in git history
wisp (vapor): Ephemeral work that auto-cleans up
- Release workflows (one-time execution)
- Operational loops and recurring cycles
- Health checks and diagnostics
- Any operational workflow without audit value
TIP: Formulas can specify phase:"vapor" to recommend wisp usage.
If you pour a vapor-phase formula, you'll get a warning.
Examples:
bd mol pour mol-feature --var name=auth # Persistent feature work
bd mol pour mol-review --var pr=123 # Persistent code review
```
bd mol pour <proto-id> [flags]
```
**Flags:**
```
--assignee string Assign the root issue to this agent/user
--attach strings Proto to attach after spawning (repeatable)
--attach-type string Bond type for attachments: sequential, parallel, or conditional (default "sequential")
--dry-run Preview what would be created
--var stringArray Variable substitution (key=value)
```
## bd mol progress
Show efficient progress summary for a molecule.
This command uses indexed queries to count progress without loading all steps,
making it suitable for very large molecules (millions of steps).
If no molecule-id is given, shows progress for any molecule you're working on.
Output includes:
- Progress: completed / total (percentage)
- Current step: the in-progress step (if any)
- Rate: steps/hour based on closure times
- ETA: estimated time to completion
Example:
bd mol progress bd-hanoi-xyz
```
bd mol progress [molecule-id] [flags]
```
## bd mol ready
Find molecules where a gate has closed and the workflow is ready to resume.
This command discovers molecules waiting at a gate step where:
1. The molecule has a gate bead that blocks a step
2. The gate bead is now closed (condition satisfied)
3. The blocked step is now ready to proceed
4. No agent currently has this molecule hooked
This enables discovery-based resume without explicit waiter tracking.
The patrol system uses this to find and dispatch gate-ready molecules.
Examples:
bd mol ready --gated # Find all gate-ready molecules
bd mol ready --gated --json # JSON output for automation
```
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.
The seed command checks formula search paths to ensure a formula exists
and can be loaded. This is useful for verifying system health before
attempting to spawn work from a formula.
Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula
bd mol seed mol-review --var name=test # Verify with variable substitution
```
bd mol seed <formula-name> [flags]
```
**Flags:**
```
--var stringArray Variable substitution for condition filtering (key=value)
```
## bd mol show
Show molecule structure and details.
The --parallel flag highlights parallelizable steps:
- Steps with no blocking dependencies can run in parallel
- Shows which steps are ready to start now
- Identifies parallel groups (steps that can run concurrently)
Example:
bd mol show bd-patrol --parallel
```
bd mol show <molecule-id> [flags]
```
**Flags:**
```
-p, --parallel Show parallel step analysis
```
## bd mol squash
Squash a molecule's ephemeral children into a single digest issue.
This command collects all ephemeral child issues of a molecule (Ephemeral=true),
generates a summary digest, and promotes the wisps to persistent by
clearing their Wisp flag (or optionally deletes them).
The squash operation:
1. Loads the molecule and all its children
2. Filters to only wisps (ephemeral issues with Ephemeral=true)
3. Generates a digest (summary of work done)
4. Creates a permanent digest issue (Ephemeral=false)
5. Clears Wisp flag on children (promotes to persistent)
OR keeps them with --keep-children (default: delete)
AGENT INTEGRATION:
Use --summary to provide an AI-generated summary. This keeps bd as a pure
tool - the calling agent (orchestrator worker, Claude Code, etc.) is responsible
for generating intelligent summaries. Without --summary, a basic concatenation
of child issue content is used.
This is part of the wisp workflow: spawn creates wisps,
execution happens, squash compresses the trace into an outcome (digest).
Example:
bd mol squash bd-abc123 # Squash and promote children
bd mol squash bd-abc123 --dry-run # Preview what would be squashed
bd mol squash bd-abc123 --keep-children # Keep wisps after digest
bd mol squash bd-abc123 --summary "Agent-generated summary of work done"
```
bd mol squash <molecule-id> [flags]
```
**Flags:**
```
--dry-run Preview what would be squashed
--keep-children Don't delete ephemeral children after squash
--summary string Agent-provided summary (bypasses auto-generation)
```
## bd mol stale
Detect molecules (epics with children) that are complete but still open.
A molecule is considered stale if:
1. All children are closed (Completed == Total)
2. Root issue is still open
3. Not assigned to anyone (optional, use --unassigned)
4. Is blocking other work (optional, use --blocking)
By default, shows all complete-but-unclosed molecules.
Examples:
bd mol stale # List all stale molecules
bd mol stale --json # Machine-readable output
bd mol stale --blocking # Only show those blocking other work
bd mol stale --unassigned # Only show unassigned molecules
bd mol stale --all # Include molecules with 0 children
```
bd mol stale [flags]
```
**Flags:**
```
--all Include molecules with 0 children
--blocking Only show molecules blocking other work
--unassigned Only show unassigned molecules
```
## bd mol wisp
Create or manage wisps - EPHEMERAL molecules for operational workflows.
When called with a proto-id argument, creates a wisp from that proto.
When called with a subcommand (list, gc), manages existing wisps.
Wisps are issues with Ephemeral=true in the main database. They're stored
locally but NOT synced via git.
WHEN TO USE WISP vs POUR:
wisp (vapor): Ephemeral work that auto-cleans up
- Release workflows (one-time execution)
- Operational loops and recurring cycles
- Health checks and diagnostics
- Any operational workflow without audit value
pour (liquid): Persistent work that needs audit trail
- Feature implementations spanning multiple sessions
- Work you may need to reference later
- Anything worth preserving in git history
TIP: Formulas can specify phase:"vapor" to recommend wisp usage.
If you use pour on a vapor-phase formula, you'll get a warning.
The wisp lifecycle:
1. Create: bd mol wisp &lt;proto&gt; or bd create --ephemeral
2. Execute: Normal bd operations work on wisp issues
3. Squash: bd mol squash &lt;id&gt; (clears Ephemeral flag, promotes to persistent)
4. Or burn: bd mol burn &lt;id&gt; (deletes without creating digest)
Examples:
bd mol wisp beads-release --var version=1.0 # Release workflow
bd mol wisp mol-my-workflow # Ephemeral operational cycle
bd mol wisp list # List all wisps
bd mol wisp gc # Garbage collect old wisps
Subcommands:
list List all wisps in current context
gc Garbage collect orphaned wisps
```
bd mol wisp [proto-id] [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--root-only Create only the root issue (no child step issues)
--var stringArray Variable substitution (key=value)
```
### bd mol wisp create
Create a wisp from a proto - sublimation from solid to vapor.
This is the chemistry-inspired command for creating ephemeral work from templates.
The resulting wisp is stored in the main database with Ephemeral=true and NOT synced via git.
Phase transition: Proto (solid) -&gt; Wisp (vapor)
Use wisp for:
- Operational loops and recurring cycles
- Health checks and monitoring
- One-shot orchestration runs
- Routine operations with no audit value
The wisp will:
- Be stored in main database with Ephemeral=true flag
- NOT be synced via git
- Either evaporate (burn) or condense to digest (squash)
Examples:
bd mol wisp create mol-patrol # Ephemeral patrol cycle
bd mol wisp create mol-health-check # One-time health check
bd mol wisp create mol-diagnostics --var target=db # Diagnostic run
```
bd mol wisp create <proto-id> [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--root-only Create only the root issue (no child step issues)
--var stringArray Variable substitution (key=value)
```
### bd mol wisp gc
Garbage collect old or abandoned wisps from the database.
A wisp is considered abandoned if:
- It hasn't been updated in --age duration and is not closed
Abandoned wisps are deleted without creating a digest. Use 'bd mol squash'
if you want to preserve a summary before garbage collection.
Use --closed to purge ALL closed wisps (regardless of age). This is the
fastest way to reclaim space from accumulated wisp bloat. Safe by default:
requires --force to actually delete.
Note: This uses time-based cleanup, appropriate for ephemeral wisps.
For graph-pressure staleness detection (blocking other work), see 'bd mol stale'.
Examples:
bd mol wisp gc # Clean abandoned wisps (default: 1h threshold)
bd mol wisp gc --dry-run # Preview what would be cleaned
bd mol wisp gc --age 24h # Custom age threshold
bd mol wisp gc --all # Also clean closed wisps older than threshold
bd mol wisp gc --closed # Preview closed wisp deletion
bd mol wisp gc --closed --force # Delete all closed wisps
bd mol wisp gc --closed --dry-run # Explicit dry-run (same as no --force)
bd mol wisp gc --exclude-type agent,rig # Protect agent and rig wisps from GC
bd mol wisp gc --closed --force --exclude-type mol # Delete closed wisps except mol type
```
bd mol wisp gc [flags]
```
**Flags:**
```
--age string Age threshold for abandoned wisp detection (default "1h")
--all Also clean closed wisps older than threshold
--closed Delete all closed wisps (ignores --age threshold)
--dry-run Preview what would be cleaned
--exclude-type strings Exclude wisps of these types from GC (comma-separated, e.g., agent,rig)
-f, --force Actually delete (default: preview only)
```
### bd mol wisp list
List all wisps (ephemeral molecules) in the current context.
Wisps are issues with Ephemeral=true in the main database. They are stored
locally but not synced via git.
The list shows:
- ID: Issue ID of the wisp
- Title: Wisp title
- Status: Current status (open, in_progress, closed)
- Started: When the wisp was created
- Updated: Last modification time
Old wisp detection:
- Old wisps haven't been updated in 24+ hours
- Use 'bd mol wisp gc' to clean up old/abandoned wisps
Examples:
bd mol wisp list # List all wisps
bd mol wisp list --json # JSON output for programmatic use
bd mol wisp list --all # Include closed wisps
```
bd mol wisp list [flags]
```
**Flags:**
```
--all Include closed wisps
--type string Filter by issue type (e.g., agent, task, patrol)
```

View file

@ -0,0 +1,29 @@
---
title: "bd note"
description: "Append a note to an issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc note`.
Append a note to an issue's notes field.
Shorthand for 'bd update &lt;id&gt; --append-notes "text"'.
Examples:
bd note gt-abc "Fixed the flaky test"
bd note gt-abc Fixed the flaky test
echo "note from pipe" | bd note gt-abc --stdin
bd note gt-abc --file notes.txt
```
bd note <id> [text...] [flags]
```
**Flags:**
```
--file string Read note text from file
--stdin Read note text from stdin
```

View file

@ -0,0 +1,109 @@
---
title: "bd notion"
description: "Notion integration commands"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc notion`.
Commands for syncing issues between beads and Notion.
```
bd notion [flags]
```
## bd notion connect
Connect bd to an existing Notion database or data source
```
bd notion connect [flags]
```
**Flags:**
```
--url string Existing Notion database or data source URL
```
## bd notion init
Create a dedicated Beads database in Notion
```
bd notion init [flags]
```
**Flags:**
```
--parent string Parent page ID
--title string Database title (default "Beads Issues")
```
## bd notion pull
Pull one or more items from Notion.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd notion sync --pull --issues &lt;refs&gt;
```
bd notion pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
## bd notion push
Push one or more beads issues to Notion.
Accepts bead IDs as positional arguments.
Equivalent to: bd notion sync --push --issues &lt;ids&gt;
```
bd notion push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
## bd notion status
Show Notion sync status
```
bd notion status [flags]
```
## bd notion sync
Synchronize issues between beads and Notion.
By default this performs bidirectional sync. Use --pull or --push to limit direction.
```
bd notion sync [flags]
```
**Flags:**
```
--create-only Only create missing remote pages, do not update existing ones
--dry-run Preview changes without making mutations
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-local On conflict, keep the local beads version
--prefer-notion On conflict, use the Notion version
--pull Only pull issues from Notion
--push Only push issues to Notion
--state string Issue state to sync: open, closed, or all (default "all")
```

View file

@ -0,0 +1,28 @@
---
title: "bd onboard"
description: "Display minimal snippet for agent instructions file"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc onboard`.
Display a minimal snippet to add to your agent instructions file for bd integration.
By default, the agent instructions file is AGENTS.md. Use 'bd init --agents-file'
to configure a different filename (e.g. BEADS.md).
This outputs a small (~10 line) snippet that points to 'bd prime' for full
workflow context. This is the same minimal profile that 'bd init' generates
by default. This approach:
• Keeps your agent file lean (doesn't bloat with instructions)
• bd prime provides dynamic, always-current workflow details
• Hooks auto-inject bd prime at session start
For agents or environments that do not auto-inject hook output, use
'bd init --agents-profile=full' to embed the complete command reference.
```
bd onboard [flags]
```

View file

@ -0,0 +1,33 @@
---
title: "bd orphans"
description: "Identify orphaned issues (referenced in commits but still open)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc orphans`.
Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database.
This helps identify work that has been implemented but not formally closed.
Examples:
bd orphans # Show orphaned issues
bd orphans --json # Machine-readable output
bd orphans --details # Show full commit information
bd orphans --fix # Close orphaned issues with confirmation
bd orphans --label theme:personal # Only orphans with this label
bd orphans --label-any theme:personal,theme:ventures # Orphans with either label
```
bd orphans [flags]
```
**Flags:**
```
--details Show full commit information
-f, --fix Close orphaned issues with confirmation
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
```

View file

@ -0,0 +1,26 @@
---
title: "bd ping"
description: "Check database connectivity"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc ping`.
Lightweight health check that confirms bd can reach its database.
Steps:
1. Resolve the .beads workspace
2. Open the store (embedded or server)
3. Run a trivial query (issue count)
4. Report timing
Exit 0 on success, exit 1 on failure.
Examples:
bd ping # Quick connectivity check
bd ping --json # Structured output for automation
```
bd ping [flags]
```

View file

@ -0,0 +1,38 @@
---
title: "bd preflight"
description: "Show PR readiness checklist"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc preflight`.
Display a checklist of common pre-PR checks for contributors.
This command helps catch common issues before pushing to CI:
- Tests not run locally
- Lint errors
- Unformatted Go files
- .beads/issues.jsonl pollution
- Stale nix vendorHash
- Version mismatches
Examples:
bd preflight # Show checklist
bd preflight --check # Run checks automatically
bd preflight --check --json # JSON output for programmatic use
bd preflight --check --skip-lint # Explicitly skip lint check
```
bd preflight [flags]
```
**Flags:**
```
--check Run checks automatically
--fix Auto-fix issues where possible (vendorHash, version sync)
--json Output results as JSON
--skip-lint Skip lint check explicitly
```

View file

@ -0,0 +1,60 @@
---
title: "bd prime"
description: "Output AI-optimized workflow context"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc prime`.
Output essential Beads workflow context in AI-optimized markdown format.
Automatically detects if MCP server is active and adapts output:
- MCP mode: Brief workflow reminders (~50 tokens)
- CLI mode: Full command reference (~1-2k tokens)
Designed for Claude Code, Gemini CLI, and Codex SessionStart hooks to prevent
agents from forgetting bd workflow after context compaction.
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/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 output entirely.
- Use --export to dump the default content for customization.
- Use --memories-only for hook contexts that should inject only persistent memories.
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.
```
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
--stealth Stealth mode (no git operations, flush only)
```

View file

@ -0,0 +1,27 @@
---
title: "bd priority"
description: "Set the priority of an issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc priority`.
Set the priority of an issue.
Shorthand for 'bd update &lt;id&gt; --priority &lt;n&gt;'.
Priority levels:
0 - Critical (security, data loss, broken builds)
1 - High (major features, important bugs)
2 - Medium (default)
3 - Low (polish, optimization)
4 - Backlog (future ideas)
Examples:
bd priority bd-123 0 # Critical
bd priority bd-123 2 # Medium
```
bd priority <id> <n> [flags]
```

View file

@ -0,0 +1,30 @@
---
title: "bd promote"
description: "Promote a wisp to a permanent bead"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc promote`.
Promote a wisp (ephemeral issue) to a permanent bead.
This copies the issue from the wisps table (dolt_ignored) to the permanent
issues table (Dolt-versioned), preserving labels, dependencies, events, and
comments. The original ID is preserved so all links keep working.
A comment is added recording the promotion and optional reason.
Examples:
bd promote bd-wisp-abc123
bd promote bd-wisp-abc123 --reason "Worth tracking long-term"
```
bd promote <wisp-id> [flags]
```
**Flags:**
```
-r, --reason string Reason for promotion
```

View file

@ -0,0 +1,54 @@
---
title: "bd prune"
description: "Delete old closed beads to reclaim space and shrink exports"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc prune`.
Permanently delete closed non-ephemeral beads and their associated data.
Use this to trim closed regular beads (tasks, features, bugs, chores, etc.)
that are no longer useful. The common case is a long-lived repo where
closed work has piled up and is bloating auto-export or slowing queries.
Requires --older-than or --pattern. The flag is a safety gate — without
it, a muscle-memory `--force` could wipe every closed bead in the repo.
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.
For full Dolt storage reclaim after deleting many rows, follow with `bd flatten`
so history can be collapsed and old chunks can be garbage-collected.
EXAMPLES:
bd prune --older-than 30d # Preview closed beads &gt;30d old
bd prune --older-than 30d --force # Delete them
bd prune --older-than 90d --dry-run # Detailed preview with stats
bd prune --pattern "*" --force # Delete all closed regular beads
bd prune --pattern "gm-temp-*" --force # Scope to a pattern
```
bd prune [flags]
```
**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

@ -0,0 +1,42 @@
---
title: "bd purge"
description: "Delete closed ephemeral beads to reclaim space"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc purge`.
Permanently delete closed ephemeral beads and their associated data.
Closed ephemeral beads (wisps, transient molecules) accumulate rapidly and
have no value once closed. This command removes them to reclaim storage.
Deletes: issues, dependencies, labels, events, and comments for matching beads.
Skips: pinned beads (protected).
To delete closed non-ephemeral beads (regular tasks, features, bugs, etc.)
use `bd prune` instead.
For full Dolt storage reclaim after deleting many rows, follow with `bd flatten`
so history can be collapsed and old chunks can be garbage-collected.
EXAMPLES:
bd purge # Preview what would be purged
bd purge --force # Delete all closed ephemeral beads
bd purge --older-than 7d --force # Only purge items closed 7+ days ago
bd purge --pattern "*-wisp-*" # Only purge matching ID pattern
bd purge --dry-run # Detailed preview with stats
```
bd purge [flags]
```
**Flags:**
```
--dry-run Preview what would be purged with stats
-f, --force Actually purge (without this, shows preview)
--older-than string Only purge beads closed more than N ago (e.g., 7d, 2w, 30)
--pattern string Only purge beads matching ID glob pattern (e.g., *-wisp-*)
```

30
docs/cli-reference/q.md Normal file
View file

@ -0,0 +1,30 @@
---
title: "bd q"
description: "Quick capture: create issue and output only ID"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc q`.
Quick capture creates an issue and outputs only the issue ID.
Designed for scripting and AI agent integration.
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]
```
**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

@ -0,0 +1,82 @@
---
title: "bd query"
description: "Query issues using a simple query language"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc query`.
Query issues using a simple query language that supports compound filters,
boolean operators, and date-relative expressions.
The query language enables complex filtering that would otherwise require
multiple flags or piping through jq.
Syntax:
field=value Equality comparison
field!=value Inequality comparison
field&gt;value Greater than
field&gt;=value Greater than or equal
field&lt;value Less than
field&lt;=value Less than or equal
Boolean operators (case-insensitive):
expr AND expr Both conditions must match
expr OR expr Either condition can match
NOT expr Negates the condition
(expr) Grouping with parentheses
Supported fields:
status Stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues stay "open"; use 'bd blocked' to find them
priority Priority level (0-4)
type Issue type (bug, feature, task, epic, chore, decision)
assignee Assigned user (use "none" for unassigned)
owner Issue owner
label Issue label (use "none" for unlabeled)
title Search in title (contains)
description Search in description (contains, "none" for empty)
notes Search in notes (contains)
created Creation date/time
updated Last update date/time
started Date/time issue first transitioned to in_progress
closed Close date/time
id Issue ID (supports wildcards: bd-*)
spec Spec ID (supports wildcards)
pinned Boolean (true/false)
ephemeral Boolean (true/false)
template Boolean (true/false)
parent Parent issue ID
mol_type Molecule type (swarm, patrol, work)
Date values:
Relative durations: 7d (7 days ago), 24h (24 hours ago), 2w (2 weeks ago)
Absolute dates: 2025-01-15, 2025-01-15T10:00:00Z
Natural language: tomorrow, "next monday", "in 3 days"
Examples:
bd query "status=open AND priority&gt;1"
bd query "status=open AND priority&lt;=2 AND updated&gt;7d"
bd query "(status=open OR status=blocked) AND priority&lt;2"
bd query "type=bug AND label=urgent"
bd query "NOT status=closed"
bd query "assignee=none AND type=task"
bd query "created&gt;30d AND status!=closed"
bd query "label=frontend OR label=backend"
bd query "title=authentication AND priority=0"
```
bd query [expression] [flags]
```
**Flags:**
```
-a, --all Include closed issues (default: exclude closed)
-n, --limit int Limit results (default: 50, 0 = unlimited) (default 50)
--long Show detailed multi-line output for each issue
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
--parse-only Only parse the query and show the AST (for debugging)
-r, --reverse Reverse sort order
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
```

View file

@ -0,0 +1,14 @@
---
title: "bd quickstart"
description: "Quick start guide for bd"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc quickstart`.
Display a quick start guide showing common bd workflows and patterns.
```
bd quickstart [flags]
```

View file

@ -0,0 +1,58 @@
---
title: "bd ready"
description: "Show ready work (open, no active blockers)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc ready`.
Show ready work (open issues with no active blockers).
Excludes in_progress, blocked, deferred, and hooked issues. This uses the
GetReadyWork API which applies blocker-aware semantics to find truly claimable work.
Note: 'bd list --ready' uses the same blocker-aware ready-work semantics.
Use --mol to filter to a specific molecule's steps:
bd ready --mol bd-patrol # Show ready steps within molecule
Use --gated to find molecules ready for gate-resume dispatch:
bd ready --gated # Find molecules where a gate closed
Use --claim to atomically claim the first ready issue matching the filters:
bd ready --claim --json
This is useful for agents executing molecules to see which steps can run next.
```
bd ready [flags]
```
**Flags:**
```
-a, --assignee string Filter by assignee
--claim Atomically claim the first ready issue matching the filters
--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)
--explain Show dependency-aware reasoning for why issues are ready or blocked
--gated Find molecules ready for gate-resume dispatch
--has-metadata-key string Filter issues that have this metadata key set
--include-deferred Include issues with future defer_until timestamps
--include-ephemeral Include ephemeral issues (wisps) in results
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
-n, --limit int Maximum issues to show (use 0 for unlimited) (default 100)
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
--mol string Filter to steps within a specific molecule
--mol-type string Filter by molecule type: swarm, patrol, or work
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
--parent string Filter to descendants of this bead/epic
--plain Display issues as a plain numbered list
--pretty Display issues in a tree format with status/priority symbols (default true)
-p, --priority int Filter by priority
-s, --sort string Sort policy: priority (default), hybrid, oldest (default "priority")
-t, --type string Filter by issue type (task, bug, feature, epic, decision, merge-request). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision
-u, --unassigned Show only unassigned issues
```

View file

@ -0,0 +1,18 @@
---
title: "bd recall"
description: "Retrieve a specific memory"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc recall`.
Retrieve the full content of a memory by its key.
Examples:
bd recall dolt-phantoms
bd recall auth-jwt
```
bd recall <key> [flags]
```

View file

@ -0,0 +1,37 @@
---
title: "bd reclaim"
description: "Revert stale-lease in_progress issues back to ready (dead-worker recovery)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc reclaim`.
Revert in_progress issues whose lease has gone stale back to ready.
When a worker claims an issue it takes a lease that expires after a TTL, kept
alive by 'bd heartbeat'. A worker that dies stops heartbeating, so its lease
expires and its issue would otherwise stay in_progress forever. reclaim is the
reaper: it finds in_progress issues whose lease expired more than --older-than
ago, clears the assignee, and sets them back to open so another worker can
claim them. The previous owner's stale lease is recorded as a recovery event.
--older-than is a grace window past lease expiry: only leases that expired at
least this long ago are reclaimed, so a worker briefly paused (GC, clock skew)
is not robbed of live work. Run it from a supervisor on a timer with a window
of roughly 2× the claim TTL.
Examples:
bd reclaim # default grace window (2× the lease TTL)
bd reclaim --older-than 10m # reclaim leases expired &gt;10m ago
bd reclaim --older-than 0s # reclaim every currently-expired lease
```
bd reclaim [flags]
```
**Flags:**
```
--older-than duration Only reclaim leases that expired at least this long ago (grace window) (default 10m0s)
```

View file

@ -0,0 +1,30 @@
---
title: "bd recompute-blocked"
description: "Recompute is_blocked for all issues (repairs stale flags after a pull)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc recompute-blocked`.
Recompute the denormalized is_blocked flag for every issue and wisp.
is_blocked is derived from the dependency graph and maintained automatically by
local writes and by a post-pull recompute scoped to what the merge changed. If
that scoped recompute is skipped — a recompute that failed after its merge
committed, or a conflicted pull resolved by hand — the flag can go stale, and a
later pull that merges nothing will not refresh it (bd-6dnrw.37). 'bd ready'
trusts the flag, so stale values silently hide ready work or surface blocked
work.
This command runs the full recompute unconditionally and commits the result.
It is idempotent: on a consistent database it changes nothing. Works in both
embedded and server mode (unlike 'bd doctor', which is server-mode only).
Examples:
bd recompute-blocked # Repair stale is_blocked flags
bd recompute-blocked --json # Machine-parseable &#123;"rows_corrected": N&#125;
```
bd recompute-blocked [flags]
```

View file

@ -0,0 +1,34 @@
---
title: "bd remember"
description: "Store a persistent memory"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc remember`.
Store a memory that persists across sessions and account rotations.
Memories are injected at prime time (bd prime) so you have them
in every session without manual loading.
The positional arg is the memory CONTENT (the key is auto-generated from it
unless --key is given). As a convenience, if the arg is a bare key naming an
existing memory, it is RECALLED instead of stored (same as 'bd recall');
a bare key naming nothing is refused. Use --key to store slug-like content.
Examples:
bd remember "always run tests with -race flag"
bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms
bd remember "auth module uses JWT not sessions" --key auth-jwt
bd remember dolt-phantoms # bare existing key: reads it (= bd recall)
```
bd remember "<insight>" [flags]
```
**Flags:**
```
--key string Explicit key for the memory (auto-generated from content if not set). If a memory with this key already exists, it will be updated in place
```

View file

@ -0,0 +1,47 @@
---
title: "bd rename-prefix"
description: "Rename the issue prefix for all issues in the database"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc rename-prefix`.
Rename the issue prefix for all issues in the database.
This will update all issue IDs and all text references across all fields.
USE CASES:
- Shortening long prefixes (e.g., 'knowledge-work-' → 'kw-')
- Rebranding project naming conventions
- Consolidating multiple prefixes after database corruption
- Migrating to team naming standards
Prefix validation rules:
- Max length: 8 characters
- Allowed characters: lowercase letters, numbers, hyphens
- Must start with a letter
- Must end with a hyphen (e.g., 'kw-', 'work-')
- Cannot be empty or just a hyphen
Multiple prefix detection and repair:
If issues have multiple prefixes (corrupted database), use --repair to consolidate them.
The --repair flag will rename all issues with incorrect prefixes to the new prefix,
preserving issues that already have the correct prefix.
EXAMPLES:
bd rename-prefix kw- # Rename from 'knowledge-work-' to 'kw-'
bd rename-prefix mtg- --repair # Consolidate multiple prefixes into 'mtg-'
bd rename-prefix team- --dry-run # Preview changes without applying
NOTE: This is a rare operation. Most users never need this command.
```
bd rename-prefix <new-prefix> [flags]
```
**Flags:**
```
--dry-run Preview changes without applying them
--repair Repair database with multiple prefixes by consolidating them
```

View file

@ -0,0 +1,26 @@
---
title: "bd rename"
description: "Rename an issue ID"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc rename`.
Rename an issue from one ID to another.
This updates:
- The issue's primary ID
- All references in other issues (descriptions, titles, notes, etc.)
- Dependencies pointing to/from this issue
- Labels, comments, and events
Examples:
bd rename bd-w382l bd-dolt # Rename to memorable ID
bd rename gt-abc123 gt-auth # Use descriptive ID
Note: The new ID must use a valid prefix for this database.
```
bd rename <old-id> <new-id> [flags]
```

View file

@ -0,0 +1,21 @@
---
title: "bd reopen"
description: "Reopen one or more closed issues"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc reopen`.
Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp.
This is more explicit than 'bd update --status open' and emits a Reopened event.
```
bd reopen [id...] [flags]
```
**Flags:**
```
-r, --reason string Reason for reopening
```

110
docs/cli-reference/repo.md Normal file
View file

@ -0,0 +1,110 @@
---
title: "bd repo"
description: "Manage multiple repository configuration"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc repo`.
Configure and manage multiple repository support for multi-repo hydration.
Multi-repo support allows hydrating issues from multiple beads repositories
into a single database for unified cross-repo issue tracking.
Configuration is stored in .beads/config.yaml under the 'repos' section:
repos:
primary: "."
additional:
- ~/beads-planning
- ~/work-repo
Examples:
bd repo add ~/beads-planning # Add planning repo
bd repo add ../other-repo # Add relative path repo
bd repo list # Show all configured repos
bd repo remove ~/beads-planning # Remove by path
bd repo sync # Sync from all configured repos
```
bd repo [flags]
```
## bd repo add
Add a repository path to the repos.additional list in config.yaml.
The path should point to a directory containing a .beads folder.
Paths can be absolute or relative (they are stored as-is).
This modifies .beads/config.yaml, which is version-controlled and
shared across all clones of this repository.
```
bd repo add <path> [flags]
```
**Flags:**
```
--json Output JSON
```
## bd repo list
List all repositories configured in .beads/config.yaml.
Shows the primary repository (always ".") and any additional
repositories configured for hydration.
```
bd repo list [flags]
```
**Flags:**
```
--json Output JSON
```
## bd repo remove
Remove a repository path from the repos.additional list in config.yaml.
The path must exactly match what was added (e.g., if you added "~/foo",
you must remove "~/foo", not "/home/user/foo").
This command also removes any previously-hydrated issues from the database
that came from the removed repository.
```
bd repo remove <path> [flags]
```
**Flags:**
```
--json Output JSON
```
## bd repo sync
Synchronize issues from all configured additional repositories.
Reads issues.jsonl from each additional repository and imports them into
the primary database with their original prefixes and source_repo set.
Uses mtime caching to skip repos whose JSONL hasn't changed.
Also triggers Dolt push/pull if a remote is configured.
```
bd repo sync [flags]
```
**Flags:**
```
--json Output JSON
--verbose Show detailed sync progress
```

View file

@ -0,0 +1,33 @@
---
title: "bd restore"
description: "Restore the pre-compaction content of a compacted issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc restore`.
Restore the pre-compaction content of a compacted issue.
When an issue is compacted, its description/design/notes/acceptance criteria
are summarized and the originals are archived to a compaction snapshot. This
command recovers that original content.
By default it is read-only: it displays the archived content without modifying
the database. Pass --apply to write the original content back into the issue
and step its compaction level back down.
If no archived snapshot exists (e.g. the issue was compacted by an older bd
before snapshot archiving), restore falls back to a best-effort reconstruction
from Dolt version history, which can only be displayed, not applied.
```
bd restore <issue-id> [flags]
```
**Flags:**
```
--apply Write the restored content back into the issue (default: display only)
--json Output restore results in JSON format
```

View file

@ -0,0 +1,46 @@
---
title: "bd rules"
description: "Audit and compact Claude rules"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc rules`.
Audit and compact Claude rules
```
bd rules [flags]
```
## bd rules audit
Scan rules for contradictions and merge opportunities
```
bd rules audit [flags]
```
**Flags:**
```
--path string Path to rules directory (default ".claude/rules/")
--threshold float Jaccard similarity threshold (default 0.6)
```
## bd rules compact
Merge related rules into composites
```
bd rules compact [flags]
```
**Flags:**
```
--auto Apply audit suggestions
--dry-run Preview without applying
--group strings Rule names to merge
--path string Path to rules directory (default ".claude/rules/")
```

View file

@ -0,0 +1,63 @@
---
title: "bd search"
description: "Search issues by text query"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc search`.
Search issues across title and ID (excludes closed issues by default).
ID-like queries (e.g., "bd-123", "hq-319") use fast exact/prefix matching.
Text queries search titles. Use --desc-contains for description search.
Use --status all to include closed issues.
Examples:
bd search "authentication bug"
bd search "login" --status open
bd search "database" --label backend --limit 10
bd search --query "performance" --assignee alice
bd search "bd-5q" # Search by partial ID (fast prefix match)
bd search "security" --priority-min 0 --priority-max 2
bd search "bug" --created-after 2025-01-01
bd search "refactor" --status all # Include closed issues
bd search "bug" --sort priority
bd search "task" --sort created --reverse
bd search "api" --desc-contains "endpoint"
bd search "cleanup" --no-assignee --no-labels
```
bd search [query] [flags]
```
**Flags:**
```
-a, --assignee string Filter by assignee
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--desc-contains string Filter by description substring (case-insensitive)
--empty-description Filter issues with empty or missing description
--external-contains string Filter by external ref substring (case-insensitive)
--has-metadata-key string Filter issues that have this metadata key set
-l, --label strings Filter by labels (AND: must have ALL)
--label-any strings Filter by labels (OR: must have AT LEAST ONE)
-n, --limit int Limit results (default: 50) (default 50)
--long Show detailed multi-line output for each issue
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--notes-contains string Filter by notes substring (case-insensitive)
--priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4)
--priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4)
--query string Search query (alternative to positional argument)
-r, --reverse Reverse sort order
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed, all). Default excludes closed; use 'all' to include closed. Note: dependency-blocked issues use 'bd blocked'
-t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
```

View file

@ -0,0 +1,37 @@
---
title: "bd set-state"
description: "Set operational state (creates event + updates label)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc set-state`.
Atomically set operational state on an issue.
This command:
1. Creates an event bead recording the state change (source of truth)
2. Removes any existing label for the dimension
3. Adds the new dimension:value label (fast lookup cache)
State labels follow the convention &lt;dimension&gt;:&lt;value&gt;, for example:
patrol:active, patrol:muted
mode:normal, mode:degraded
health:healthy, health:failing
Examples:
bd set-state agent-abc patrol=muted --reason "Investigating stuck worker"
bd set-state agent-abc mode=degraded --reason "High error rate detected"
bd set-state agent-abc health=healthy
The --reason flag provides context for the event bead (recommended).
```
bd set-state <issue-id> <dimension>=<value> [flags]
```
**Flags:**
```
--reason string Reason for the state change (recorded in event)
```

View file

@ -0,0 +1,48 @@
---
title: "bd setup"
description: "Setup integration with AI editors"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc setup`.
Setup integration files for AI editors and coding assistants.
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 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
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers
bd setup --list # Show all available recipes
bd setup --print # Print the template to stdout
bd setup -o rules.md # Write template to custom path
bd setup --add myeditor .myeditor/rules.md # Add custom recipe
Use 'bd setup &lt;recipe&gt; --check' to verify installation status.
Use 'bd setup &lt;recipe&gt; --remove' to uninstall.
```
bd setup [recipe] [flags]
```
**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)
--list List all available recipes
-o, --output string Write template to custom path
--print Print the template to stdout
--project Install for this project only (gemini/mux)
--remove Remove the integration
--stealth Use stealth mode (claude/gemini)
```

View file

@ -0,0 +1,37 @@
---
title: "bd ship"
description: "Publish a capability for cross-project dependencies"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc ship`.
Ship a capability to satisfy cross-project dependencies.
This command:
1. Finds issue with export:&lt;capability&gt; label
2. Validates issue is closed (or --force to override)
3. Adds provides:&lt;capability&gt; label
External projects can depend on this capability using:
bd dep add &lt;issue&gt; external:&lt;project&gt;:&lt;capability&gt;
The capability is resolved when the external project has a closed issue
with the provides:&lt;capability&gt; label.
Examples:
bd ship mol-run-assignee # Ship the mol-run-assignee capability
bd ship mol-run-assignee --force # Ship even if issue is not closed
bd ship mol-run-assignee --dry-run # Preview without making changes
```
bd ship <capability> [flags]
```
**Flags:**
```
--dry-run Preview without making changes
--force Ship even if issue is not closed
```

View file

@ -0,0 +1,33 @@
---
title: "bd show"
description: "Show issue details"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc show`.
Show issue details
```
bd show [id...] [--id=<id>...] [--current] [flags]
```
**Aliases:** view
**Flags:**
```
--as-of string Show issue as it existed at a specific commit hash or branch (requires Dolt)
--children Show only the children of this issue
--current Show the currently active issue (in-progress, hooked, or last touched)
--id stringArray Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz)
--include-comments Stream full comment bodies in JSON output (--json only; may be slow on issues with many comments)
--include-dependents Stream full dependent issues in JSON output (--json only; may be slow on hub beads)
--local-time Show timestamps in local time instead of UTC
--long Show all available fields (extended metadata, agent identity, gate fields, etc.)
--refs Show issues that reference this issue (reverse lookup)
--short Show compact one-line output per issue
--thread Show full conversation thread (for messages)
-w, --watch Watch for changes and auto-refresh display
```

34
docs/cli-reference/sql.md Normal file
View file

@ -0,0 +1,34 @@
---
title: "bd sql"
description: "Execute raw SQL against the beads database"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc sql`.
Execute a raw SQL query against the underlying database (SQLite or Dolt).
Useful for debugging, maintenance, and working around bugs in higher-level commands.
Examples:
bd sql 'SELECT COUNT(*) FROM issues'
bd sql 'SELECT id, title FROM issues WHERE status = "open" LIMIT 5'
bd sql 'DELETE FROM dirty_issues WHERE issue_id = "bd-abc123"'
bd sql --csv 'SELECT id, title, status FROM issues'
The query is passed directly to the database. SELECT queries return results as a
table (or JSON/CSV with --json/--csv). Non-SELECT queries (INSERT, UPDATE, DELETE)
report the number of rows affected.
WARNING: Direct database access bypasses the storage layer. Use with caution.
```
bd sql <query> [flags]
```
**Flags:**
```
--csv Output results in CSV format
```

View file

@ -0,0 +1,26 @@
---
title: "bd stale"
description: "Show stale issues (not updated recently)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc stale`.
Show issues that haven't been updated recently and may need attention.
This helps identify:
- In-progress issues with no recent activity (may be abandoned)
- Open issues that have been forgotten
- Issues that might be outdated or no longer relevant
```
bd stale [flags]
```
**Flags:**
```
-d, --days int Issues not updated in this many days (default 30)
-n, --limit int Maximum issues to show (default 50)
-s, --status string Filter by status (open|in_progress|blocked|deferred)
```

View file

@ -0,0 +1,43 @@
---
title: "bd state"
description: "Query the current value of a state dimension"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc state`.
Query the current value of a state dimension from an issue's labels.
State labels follow the convention &lt;dimension&gt;:&lt;value&gt;, for example:
patrol:active
mode:degraded
health:healthy
This command extracts the value for a given dimension.
Examples:
bd state witness-abc patrol # Output: active
bd state witness-abc mode # Output: normal
bd state witness-abc health # Output: healthy
```
bd state <issue-id> <dimension> [flags]
```
## bd state list
List all state labels (dimension:value format) on an issue.
This filters labels to only show those following the state convention.
Example:
bd state list witness-abc
# Output:
# patrol: active
# mode: normal
# health: healthy
```
bd state list <issue-id> [flags]
```

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