bd — Complete Command Reference

Reference for bd Latest. Generated from bd help --all.

Table of Contents

Working With Issues:

• bd assign — Assign an issue to someone
• bd children — List child beads of a parent
• bd close — Close one or more issues
• bd comment — Add a comment to an issue
• bd comments — View or manage comments on an issue
  • bd comments add — Add a comment to an issue
  • bd comments list — Invalid — use bd comments <issue-id> to list comments
• bd create — Create a new issue (or batch from markdown/graph JSON)
• bd create-form — Create a new issue using an interactive form
• bd delete — Delete one or more issues and clean up references
• bd edit — Edit an issue field in $EDITOR
• bd gate — Manage async coordination gates
  • bd gate add-waiter — Add a waiter to a gate
  • bd gate check — Evaluate gates and close resolved ones
  • bd gate create — Create a gate that blocks an issue
  • bd gate discover — Discover await_id for gh:run gates
  • bd gate list — List gate issues
  • bd gate resolve — Manually resolve (close) a gate
  • bd gate show — Show a gate issue
• bd label — Manage issue labels
  • bd label add — Add a label to one or more issues
  • bd label list — List labels for an issue
  • bd label list-all — List all unique labels in the database
  • bd label propagate — Propagate a label from a parent issue to all its children
  • bd label remove — Remove a label from one or more issues
• bd link — Link two issues with a dependency
• bd list — List issues
• bd merge-slot — Manage merge-slot gates for serialized conflict resolution
  • bd merge-slot acquire — Acquire the merge slot
  • bd merge-slot check — Check merge slot availability
  • bd merge-slot create — Create a merge slot bead for the current rig
  • bd merge-slot release — Release the merge slot
• bd note — Append a note to an issue
• bd priority — Set the priority of an issue
• bd promote — Promote a wisp to a permanent bead
• bd q — Quick capture: create issue and output only ID
• bd query — Query issues using a simple query language
• bd reopen — Reopen one or more closed issues
• bd search — Search issues by text query
• bd set-state — Set operational state (creates event + updates label)
• bd show — Show issue details
• bd state — Query the current value of a state dimension
  • bd state list — List all state dimensions on an issue
• bd tag — Add a label to an issue
• bd todo — Manage TODO items (convenience wrapper for task issues)
  • bd todo add — Add a new TODO item
  • bd todo done — Mark TODO(s) as done
  • bd todo list — List TODO items
• bd update — Update one or more issues

Views & Reports:

• bd count — Count issues matching filters
• bd diff — Show changes between two commits or branches
• bd find-duplicates — Find semantically similar issues using text analysis or AI
• bd history — Show version history for an issue
• bd lint — Check issues for missing template sections
• bd stale — Show stale issues (not updated recently)
• bd status — Show issue database overview and statistics
• bd statuses — List valid issue statuses
• bd types — List valid issue types

Dependencies & Structure:

• bd dep — Manage dependencies
  • bd dep add — Add a dependency
  • bd dep cycles — Detect dependency cycles
  • bd dep list — List dependencies or dependents of one or more issues
  • bd dep relate — Create a bidirectional relates_to link between issues
  • bd dep remove — Remove a dependency
  • bd dep tree — Show dependency tree
  • bd dep unrelate — Remove a relates_to link between issues
• bd duplicate — Mark an issue as a duplicate of another
• bd duplicates — Find and optionally merge duplicate issues
• bd epic — Epic management commands
  • bd epic close-eligible — Close epics where all children are complete
  • bd epic status — Show epic completion status
• bd graph — Display issue dependency graph
  • bd graph check — Check dependency graph integrity
• bd supersede — Mark an issue as superseded by a newer one
• bd swarm — Swarm management for structured epics
  • bd swarm create — Create a swarm molecule from an epic
  • bd swarm list — List all swarm molecules
  • bd swarm status — Show current swarm status
  • bd swarm validate — Validate epic structure for swarming

Sync & Data:

• bd backup — Back up your beads database
  • bd backup init — Set up a Dolt backup destination
  • bd backup remove — Remove the configured backup destination
  • bd backup restore — Restore database from a Dolt backup
  • bd backup status — Show last backup status
  • bd backup sync — Push database to configured Dolt backup
• bd branch — List or create branches
• bd export — Export issues to JSONL format
• bd federation — Manage peer-to-peer federation (requires CGO)
• bd import — Import issues from a JSONL file or stdin into the database
• bd restore — Restore full history of a compacted issue from Dolt history
• bd vc — Version control operations
  • bd vc commit — Create a commit with all staged changes
  • bd vc merge — Merge a branch into the current branch
  • bd vc status — Show current branch and uncommitted changes

Setup & Configuration:

• bd bootstrap — Non-destructive database setup for fresh clones and recovery
• bd config — Manage configuration settings
  • bd config apply — Reconcile system state to match configuration
  • bd config drift — Detect config-vs-reality inconsistencies
  • bd config get — Get a configuration value
  • bd config list — List all configuration
  • bd config set — Set a configuration value
  • bd config set-many — Set multiple configuration values in one operation
  • bd config show — Show all effective configuration with provenance
  • bd config unset — Delete a configuration value
  • bd config validate — Validate sync-related configuration
• bd context — Show effective backend identity and repository context
• bd dolt — Configure Dolt database settings
  • bd dolt clean-databases — Drop stale test databases from the Dolt server
  • bd dolt commit — Create a Dolt commit from pending changes
  • bd dolt killall — Kill all orphan Dolt server processes
  • bd dolt pull — Pull commits from Dolt remote
  • bd dolt push — Push commits to Dolt remote
  • bd dolt remote — Manage Dolt remotes
  • bd dolt set — Set a Dolt configuration value
  • bd dolt show — Show current Dolt configuration with connection status
  • bd dolt start — Start the Dolt SQL server for this project
  • bd dolt status — Show Dolt engine status
  • bd dolt stop — Stop the Dolt SQL server for this project
  • bd dolt test — Test connection to Dolt server
• bd forget — Remove a persistent memory
• bd hooks — Manage git hooks for beads integration
  • bd hooks install — Install bd git hooks
  • bd hooks list — List installed git hooks status
  • bd hooks run — Execute a git hook (called by thin shims)
  • bd hooks uninstall — Uninstall bd git hooks
• bd human — Show essential commands for human users
  • bd human dismiss — Dismiss a human-needed bead
  • bd human list — List all human-needed beads
  • bd human respond — Respond to a human-needed bead
  • bd human stats — Show summary statistics for human-needed beads
• bd info — Show database information
• bd init — Initialize bd in the current directory
• bd kv — Key-value store commands
  • bd kv clear — Delete a key-value pair
  • bd kv get — Get a value by key
  • bd kv list — List all key-value pairs
  • bd kv set — Set a key-value pair
• bd memories — List or search persistent memories
• bd onboard — Display minimal snippet for agent instructions file
• bd prime — Output AI-optimized workflow context
• bd quickstart — Quick start guide for bd
• bd recall — Retrieve a specific memory
• bd remember — Store a persistent memory
• bd setup — Setup integration with AI editors
• bd where — Show active beads location

Maintenance:

• bd batch — Run multiple write operations in a single database transaction
• bd compact — Squash old Dolt commits to reduce history size
• bd doctor — Check and fix beads installation health (start here)
• bd flatten — Squash all Dolt history into a single commit
• bd gc — Garbage collect: decay old issues, compact Dolt commits, run Dolt GC
• bd migrate — Database migration commands
  • bd migrate hooks — Plan or apply git hook migration to marker-managed format
  • bd migrate issues — Move issues between repositories
  • bd migrate sync — Set up sync.branch workflow for multi-clone setups
• bd ping — Check database connectivity
• bd preflight — Show PR readiness checklist
• bd prune — Delete old closed beads to reclaim space and shrink exports
• bd purge — Delete closed ephemeral beads to reclaim space
• bd rename-prefix — Rename the issue prefix for all issues in the database
• bd rules — Audit and compact Claude rules
  • bd rules audit — Scan rules for contradictions and merge opportunities
  • bd rules compact — Merge related rules into composites
• bd sql — Execute raw SQL against the beads database
• bd upgrade — Check and manage bd version upgrades
  • bd upgrade ack — Acknowledge the current bd version
  • bd upgrade review — Review changes since last bd version
  • bd upgrade status — Check if bd version has changed
• bd worktree — Manage git worktrees for parallel development
  • bd worktree create — Create a worktree
  • bd worktree info — Show worktree info for current directory
  • bd worktree list — List all git worktrees
  • bd worktree remove — Remove a worktree with safety checks

Integrations & Advanced:

• bd admin — Administrative commands for database maintenance
  • bd admin cleanup — Delete closed issues to reduce database size
  • bd admin compact — Compact old closed issues to save space
  • bd admin reset — Remove all beads data and configuration
• bd jira — Jira integration commands
  • bd jira pull — Pull specific items from Jira
  • bd jira push — Push specific beads to Jira
  • bd jira status — Show Jira sync status
  • bd jira sync — Synchronize issues with Jira
• bd linear — Linear integration commands
  • bd linear pull — Pull specific items from Linear
  • bd linear push — Push specific beads to Linear
  • bd linear status — Show Linear sync status
  • bd linear sync — Synchronize issues with Linear
  • bd linear teams — List available Linear teams
• bd repo — Manage multiple repository configuration
  • bd repo add — Add an additional repository to sync
  • bd repo list — List all configured repositories
  • bd repo remove — Remove a repository from sync configuration
  • bd repo sync — Manually trigger multi-repo sync

Other Commands:

• bd ado — Azure DevOps integration commands
  • bd ado projects — List accessible Azure DevOps projects
  • bd ado pull — Pull specific items from Azure DevOps
  • bd ado push — Push specific beads to Azure DevOps
  • bd ado status — Show Azure DevOps sync status
  • bd ado sync — Sync issues with Azure DevOps
• bd audit — Record and label agent interactions (append-only JSONL)
  • bd audit label — Append a label entry referencing an existing interaction
  • bd audit record — Append an audit interaction entry
• bd blocked — Show blocked issues
• bd completion — Generate the autocompletion script for the specified shell
  • bd completion bash — Generate the autocompletion script for bash
  • bd completion fish — Generate the autocompletion script for fish
  • bd completion powershell — Generate the autocompletion script for powershell
  • bd completion zsh — Generate the autocompletion script for zsh
• bd cook — Compile a formula into a proto (ephemeral by default)
• bd defer — Defer one or more issues for later
• bd formula — Manage workflow formulas
  • bd formula convert — Convert formula from JSON to TOML
  • bd formula list — List available formulas
  • bd formula show — Show formula details
• bd github — GitHub integration commands
  • bd github pull — Pull specific items from GitHub
  • bd github push — Push specific beads to GitHub
  • bd github repos — List accessible GitHub repositories
  • bd github status — Show GitHub sync status
  • bd github sync — Sync issues with GitHub
• bd gitlab — GitLab integration commands
  • bd gitlab projects — List accessible GitLab projects
  • bd gitlab pull — Pull specific items from GitLab
  • bd gitlab push — Push specific beads to GitLab
  • bd gitlab status — Show GitLab sync status
  • bd gitlab sync — Sync issues with GitLab
• bd help — Help about any command
• bd init-safety — Explain bd init flag semantics and the destroy-token format
• bd mail — Delegate to mail provider (e.g., gt mail)
• bd mol — Molecule commands (work templates)
  • bd mol bond — Bond two protos or molecules together
  • bd mol burn — Delete a molecule without creating a digest
  • bd mol current — Show current position in molecule workflow
  • bd mol distill — Extract a formula from an existing epic
  • bd mol last-activity — Show last activity timestamp for a molecule
  • bd mol pour — Instantiate a proto as a persistent mol (solid -> liquid)
  • bd mol progress — Show molecule progress summary
  • bd mol ready — Find molecules ready for gate-resume dispatch
  • bd mol seed — Verify formula accessibility
  • bd mol show — Show molecule details
  • bd mol squash — Compress molecule execution into a digest
  • bd mol stale — Detect complete-but-unclosed molecules
  • bd mol wisp — Create or manage wisps (ephemeral molecules)
• bd notion — Notion integration commands
  • bd notion connect — Connect bd to an existing Notion database or data source
  • bd notion init — Create a dedicated Beads database in Notion
  • bd notion pull — Pull specific items from Notion
  • bd notion push — Push specific beads to Notion
  • bd notion status — Show Notion sync status
  • bd notion sync — Sync issues with Notion
• bd orphans — Identify orphaned issues (referenced in commits but still open)
• bd ready — Show ready work (open, no active blockers)
• bd rename — Rename an issue ID
• bd ship — Publish a capability for cross-project dependencies
• bd undefer — Undefer one or more issues (restore to open)
• bd version — Print version information

Global Flags

These flags apply to all commands:

      --actor string              Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)
      --db string                 Database path (default: auto-discover .beads/*.db)
  -C, --directory string          Change to this directory before running the command (like git -C)
      --dolt-auto-commit string   Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
      --global                    Use the global shared-server database (beads_global)
      --json                      Output in JSON format
      --profile                   Generate CPU profile for performance analysis
  -q, --quiet                     Suppress non-essential output (errors only)
      --readonly                  Read-only mode: block write operations (for worker sandboxes)
      --sandbox                   Sandbox mode: disables auto-sync
  -v, --verbose                   Enable verbose/debug output

Working With Issues:

bd assign

Assign an issue to someone.

Shorthand for 'bd update <id> --assignee <name>'.

Examples: bd assign bd-123 alice bd assign bd-123 "" # unassign

bd assign <id> <name>

bd children

List all beads that are children of the specified parent bead.

This is a convenience alias for 'bd list --parent <id> --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>

bd 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).

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

bd comment

Add a comment to an issue.

Shorthand for 'bd comments add <id> "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

bd 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 <issue-id> to list comments

bd comments list

bd 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
      --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); 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

bd 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')

bd 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)

bd 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

bd 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 <rig>:<bead-id> (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 <id> # Close a gate manually

bd gate

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>

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 <id> --json status,conclusion'
• gh:pr checks 'gh pr view <id> --json state,title'

A gate is resolved when:

• gh:run: status=completed AND conclusion=success
• gh:pr: state=MERGED
• timer: current time > 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 <gate-id>' 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>

bd label

Manage issue labels

bd label

bd label add

Add a label to one or more issues

bd label add [issue-id...] [label]

bd label list

List labels for an issue

bd label list [issue-id]

bd label list-all

List all unique labels in the database

bd label list-all

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]

bd label remove

Remove a label from one or more issues

bd label remove [issue-id...] [label]

bd link

Link two issues with a dependency.

Shorthand for 'bd dep add <id1> <id2>'. 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")

bd 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/rig/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)
      --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
      --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
      --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

bd 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: <prefix>-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

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 <holder>: slot is currently held
• not found: no merge slot exists for this rig

bd merge-slot check

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

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)

bd note

Append a note to an issue's notes field.

Shorthand for 'bd update <id> --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

bd priority

Set the priority of an issue.

Shorthand for 'bd update <id> --priority <n>'.

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>

bd 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

bd 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 [title] [flags]

Flags:

  -l, --labels strings    Labels
  -p, --priority string   Priority (0-4 or P0-P4) (default "2")
  -t, --type string       Issue type (default "task")

bd 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>value Greater than field>=value Greater than or equal field<value Less than field<=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>1" bd query "status=open AND priority<=2 AND updated>7d" bd query "(status=open OR status=blocked) AND priority<2" bd query "type=bug AND label=urgent" bd query "NOT status=closed" bd query "assignee=none AND type=task" bd query "created>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
      --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

bd 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

bd 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)

bd 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 <dimension>:<value>, 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)

bd 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)
      --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

bd state

Query the current value of a state dimension from an issue's labels.

State labels follow the convention <dimension>:<value>, 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>

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>

bd tag

Add a label to an issue.

Shorthand for 'bd update <id> --add-label <label>'.

Examples: bd tag bd-123 bug bd tag bd-123 needs-review

bd tag <id> <label>

bd todo

Manage TODO items as lightweight task issues.

TODOs are regular task-type issues with convenient shortcuts: bd todo add "Title" -> bd create "Title" -t task -p 2 bd todo -> bd list --type task --status open bd todo done <id> -> bd close <id>

TODOs can be promoted to full issues by changing type or priority: bd update todo-123 --type bug --priority 0

bd todo

bd todo add

Add a new TODO item

bd todo add <title> [flags]

Flags:

  -d, --description string   Description
  -p, --priority int         Priority (0-4, default 2) (default 2)

bd todo done

Mark TODO(s) as done

bd todo done <id> [<id>...] [flags]

Flags:

      --reason string   Reason for closing (default: Completed)

bd todo list

List TODO items

bd todo list [flags]

Flags:

      --all   Show all TODOs including completed

bd update

Update one or more issues.

If no issue ID is provided, updates the last touched issue (from most recent create, update, show, or close operation).

bd update [id...] [flags]

Flags:

      --acceptance string            Acceptance criteria
      --add-label strings            Add labels (repeatable)
      --allow-empty-description      Allow empty description replacement when reading from stdin or file
      --append-notes string          Append to existing notes (with newline separator)
  -a, --assignee string              Assignee
      --await-id string              Set gate await_id (e.g., GitHub run ID for gh:run gates)
      --body-file string             Read description from file (use - for stdin)
      --claim                        Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you)
      --defer string                 Defer until date (empty to clear). Issue hidden from bd ready until then
  -d, --description string           Issue description
      --design string                Design notes
      --design-file string           Read design from file (use - for stdin)
      --due string                   Due date/time (empty to clear). Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
      --ephemeral                    Mark issue as ephemeral (wisp) - not exported to JSONL
  -e, --estimate int                 Time estimate in minutes (e.g., 60 for 1 hour)
      --external-ref string          External reference (e.g., 'gh-9', 'jira-ABC', Linear URL)
      --history                      Clear no-history flag (re-enable Dolt commit history)
      --metadata string              Set custom metadata (JSON string or @file.json to read from file)
      --no-history                   Mark issue as no-history (skip Dolt commits, not GC-eligible)
      --notes string                 Additional notes
      --parent string                New parent issue ID (reparents the issue, use empty string to remove parent)
      --persistent                   Mark issue as persistent (promote wisp to regular issue)
  -p, --priority string              Priority (0-4 or P0-P4, 0=highest)
      --remove-label strings         Remove labels (repeatable)
      --session string               Claude Code session ID for status=closed (or set CLAUDE_SESSION_ID env var)
      --set-labels strings           Set labels, replacing all existing (repeatable)
      --set-metadata stringArray     Set metadata key=value (repeatable, e.g., --set-metadata team=platform)
      --spec-id string               Link to specification document
  -s, --status string                New status
      --stdin                        Read description from stdin (alias for --body-file -)
      --title string                 New title
  -t, --type string                  New type (bug|feature|task|epic|chore|decision); custom types require types.custom config
      --unset-metadata stringArray   Remove metadata key (repeatable, e.g., --unset-metadata team)

Views & Reports:

bd 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 [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)
  -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)

bd 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>

bd 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)

bd 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)

bd 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)

bd 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)

bd status

Show a quick snapshot of the issue database state and statistics.

This command provides a summary of issue counts by state (open, in_progress, blocked, closed), ready work, extended statistics (pinned issues, average lead time), and recent activity over the last 24 hours from git history.

Similar to how 'git status' shows working tree state, 'bd status' gives you a quick overview of your issue database without needing multiple queries.

Use cases:

• Quick project health check
• Onboarding for new contributors
• Integration with shell prompts or CI/CD
• Daily standup reference

Examples: bd status # Show summary with activity bd status --no-activity # Skip git activity (faster) bd status --json # JSON format output bd status --assigned # Show issues assigned to current user bd stats # Alias for bd status

bd status [flags]

Aliases: stats

Flags:

      --all           Show all issues (default behavior)
      --assigned      Show issues assigned to current user
      --no-activity   Skip git activity tracking (faster)

bd statuses

List all valid issue statuses and their categories.

Built-in statuses (open, in_progress, blocked, etc.) are always valid. Additional statuses can be configured via status.custom:

bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen"

Categories control behavior: active — appears in 'bd ready' and default 'bd list' wip — excluded from 'bd ready', visible in default 'bd list' done — excluded from 'bd ready' and default 'bd list' frozen — excluded from 'bd ready' and default 'bd list'

Statuses without a category (legacy format) are valid but excluded from 'bd ready'.

Examples: bd statuses # List all statuses with icons and categories bd statuses --json # Output as JSON

bd statuses

bd types

List all valid issue types that can be used with bd create --type.

Core work types (bug, task, feature, chore, epic, decision) are always valid. Additional types require configuration via types.custom in .beads/config.yaml.

Examples: bd types # List all types with descriptions bd types --json # Output as JSON

bd types

Dependencies & Structure:

bd dep

Manage dependencies between issues.

When called with an issue ID and --blocks flag, creates a blocking dependency: bd dep <blocker-id> --blocks <blocked-id>

This is equivalent to: bd dep add <blocked-id> <blocker-id>

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 cycle detection after adding (use for bulk wiring — run 'bd dep cycles' to verify afterwards)

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:<project>:<capability>

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: {"from":"bd-42","to":"bd-41"}

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 cycle detection after adding (use for bulk wiring — run 'bd dep cycles' to verify afterwards)
  -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

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>

bd dep remove

Remove a dependency

bd dep remove [issue-id] [depends-on-id]

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>

bd 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)

bd 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

bd epic

Epic management commands

bd epic

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

bd 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 > 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 > graph.svg # SVG via Graphviz bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz bd graph --html issue-id > graph.html # Interactive browser view bd graph --all --html > 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

bd supersede

Mark an issue as superseded by a newer version.

The superseded issue is automatically closed with a reference to the replacement. Useful for design docs, specs, and evolving artifacts.

Examples: bd supersede bd-old --with bd-new # Mark bd-old as superseded by bd-new

bd supersede <id> --with <new> [flags]

Flags:

      --with string   Replacement issue ID (required)

bd swarm

Swarm management commands for coordinating parallel work on epics.

A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work.

bd swarm

bd swarm create

Create a swarm molecule to orchestrate parallel work on an epic.

The swarm molecule:

• Links to the epic it orchestrates
• Has mol_type=swarm for discovery
• Specifies a coordinator (optional)
• Can be picked up by any coordinator agent

If given a single issue (not an epic), it will be auto-wrapped:

• Creates an epic with that issue as its only child
• Then creates the swarm molecule for that epic

Examples: bd swarm create bd-epic-123 # Create swarm for epic bd swarm create bd-epic-123 --coordinator=observer/ # With specific coordinator bd swarm create bd-task-456 # Auto-wrap single issue

bd swarm create [epic-id] [flags]

Flags:

      --coordinator string   Coordinator address (e.g., my-project/witness)
      --force                Create new swarm even if one already exists

bd swarm list

List all swarm molecules with their status.

Shows each swarm molecule with:

• Progress (completed/total issues)
• Active workers
• Epic ID and title

Examples: bd swarm list # List all swarms bd swarm list --json # Machine-readable output

bd swarm list

bd swarm status

Show the current status of a swarm, computed from beads.

Accepts either:

• An epic ID (shows status for that epic's children)
• A swarm molecule ID (follows the link to find the epic)

Displays issues grouped by state:

• Completed: Closed issues
• Active: Issues currently in_progress (with assignee)
• Ready: Open issues with all dependencies satisfied
• Blocked: Open issues waiting on dependencies

The status is COMPUTED from beads, not stored separately. If beads changes, status changes.

Examples: bd swarm status gt-epic-123 # Show swarm status by epic bd swarm status gt-swarm-456 # Show status via swarm molecule bd swarm status gt-epic-123 --json # Machine-readable output

bd swarm status [epic-or-swarm-id]

bd swarm validate

Validate an epic's structure to ensure it's ready for swarm execution.

Checks for:

• Correct dependency direction (requirement-based, not temporal)
• Orphaned issues (roots with no dependents)
• Missing dependencies (leaves that should depend on something)
• Cycles (impossible to resolve)
• Disconnected subgraphs

Reports:

• Ready fronts (waves of parallel work)
• Estimated worker-sessions
• Maximum parallelism
• Warnings for potential issues

Examples: bd swarm validate gt-epic-123 # Validate epic structure bd swarm validate gt-epic-123 --verbose # Include detailed issue graph

bd swarm validate [epic-id] [flags]

Flags:

      --verbose   Include detailed issue graph in output

Sync & Data:

bd backup

Back up your beads database for off-machine recovery.

Commands: bd backup init <path> 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> Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication.

bd backup

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>

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

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.

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 && 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

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 <path>' first to configure a destination.

bd backup sync

bd 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]

bd 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 does not produce the JSONL backup snapshot used by 'bd backup restore'. For supported backup/restore flows, use 'bd backup', 'bd backup export-git', and 'bd backup restore'.

By default, exports only regular issues (excluding infrastructure beads like agents, rigs, 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 backup.jsonl # Export 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)
      --include-infra      Include infrastructure beads (agents, rigs, 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

bd 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

bd import

Import issues from a JSONL file (newline-delimited JSON) into the database.

If no file is specified, imports from .beads/issues.jsonl (the git-tracked export). 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 with at minimum "title". Optional fields: description, issue_type (type), priority, acceptance_criteria.

EXAMPLES: bd import # Import from .beads/issues.jsonl 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 --json # Structured output with created IDs

bd import [file|-] [flags]

Flags:

      --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

bd restore

Restore full history of a compacted issue from Dolt version history.

When an issue is compacted, its description and notes are truncated. This command queries Dolt's history tables to find the pre-compaction version and displays the full issue content.

This is read-only and does not modify the database.

bd restore <issue-id> [flags]

Flags:

      --json   Output restore results in JSON format

bd vc

Version control operations for the beads database.

These commands provide git-like version control for your issue data, including branching, merging, and viewing history.

Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access. This subcommand provides additional operations like merge and commit.

bd vc

bd vc commit

Create a new Dolt commit with all current changes.

Examples: bd vc commit -m "Added new feature issues" bd vc commit --message "Fixed priority on several issues" echo "Multi-line message" | bd vc commit --stdin

bd vc commit [flags]

Flags:

  -m, --message string   Commit message
      --stdin            Read commit message from stdin

bd vc merge

Merge the specified branch into the current branch.

If there are merge conflicts, they will be reported. You can resolve conflicts with --strategy.

Examples: bd vc merge feature-xyz # Merge feature-xyz into current branch bd vc merge feature-xyz --strategy ours # Merge, preferring our changes on conflict bd vc merge feature-xyz --strategy theirs # Merge, preferring their changes on conflict

bd vc merge <branch> [flags]

Flags:

      --strategy string   Conflict resolution strategy: 'ours' or 'theirs'

bd vc status

Show the current branch, commit hash, and any uncommitted changes.

Examples: bd vc status

bd vc status

Setup & Configuration:

bd 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 • 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)

bd 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)
• jira.* Jira integration settings
• linear.* Linear integration settings
• github.* GitHub integration settings
• custom.* Custom integration settings
• status.* Issue status configuration
• doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)

Auto-Export (config.yaml): Writes .beads/issues.jsonl after every write command (throttled). Enabled by default. Useful for viewers (bv) and git-based sync.

Keys: export.auto Enable/disable auto-export (default: true) 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: true)

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.<slug>

Examples: bd config set export.auto false # Disable auto-export bd config set export.path "beads.jsonl" # Custom export filename 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 get export.auto bd config list bd config unset jira.url

bd config

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

bd config get

Get a configuration value

bd config get <key>

bd config list

List all configuration

bd config list

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>

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

bd 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

bd 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 <k> <v> 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 <name> <url> Add a Dolt remote bd dolt remote list List configured remotes bd dolt remote remove <name> 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 <N>) 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

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_, doctest_, doctortest_, beads_pt, beads_vr*, beads_t*

These waste server memory and can degrade performance under concurrent load. Use --dry-run to see what would be dropped without actually dropping.

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

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 <name> <url> Add a new remote list List all configured remotes remove <name> Remove a remote

bd dolt remote

bd dolt remote add

Add a Dolt remote (both SQL server and CLI)

bd dolt remote add <name> <url>

bd dolt remote list

List configured Dolt remotes (SQL server + CLI)

bd dolt remote list

bd dolt remote remove

Remove a Dolt remote (both SQL server and CLI)

bd dolt remote remove <name> [flags]

Flags:

      --force   Force remove even when SQL and CLI URLs conflict

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 <N>) 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

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

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- hosted servers (dolt_mode=server with a remote dolt_server_host), pings the configured endpoint via SQL and reports reachability, server version, and database.

bd dolt status

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

bd 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>

bd 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

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

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...]

bd hooks uninstall

Remove bd git hooks from .git/hooks/ directory.

bd hooks uninstall

bd 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 <id> Respond to a human-needed bead (adds comment and closes) human dismiss <id> Dismiss a human-needed bead permanently human stats Show summary statistics for human-needed beads

bd human

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

bd 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

bd init

Initialize bd in the current directory by creating a .beads/ directory and Dolt database. Optionally specify a custom issue prefix.

Dolt is the default (and only supported) storage backend. The legacy SQLite backend has been removed. Use --backend=sqlite to see migration instructions.

Use --database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) 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 <claude|cursor|aider|...> --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 enabled by default. After every write command, bd exports issues to .beads/issues.jsonl (throttled to once per 60s). This keeps viewers (bv) and git-based workflows up to date without extra steps. To disable: bd config set export.auto false

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 (enabled) • --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 (default: dolt). --backend=sqlite prints deprecation notice.
      --contributor              Run OSS contributor setup wizard
      --database string          Use existing server database name (overrides prefix-based naming)
      --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 .beads/issues.jsonl instead of git history
      --non-interactive          Skip all interactive prompts (auto-detected in CI or non-TTY environments)
  -p, --prefix string            Issue prefix (default: current directory name)
  -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 settings generation
      --skip-hooks               Skip git hooks installation
      --stealth                  Enable stealth mode: global gitattributes and gitignore, no local repo tracking
      --team                     Run team workflow setup wizard

bd 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

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>

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>

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

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>

bd 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]

bd 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 that don't support hooks (Codex, Factory, etc.), use 'bd init --agents-profile=full' to embed the complete command reference.

bd onboard

bd 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 hooks (SessionStart, PreCompact) 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.

  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.

bd prime [flags]

Flags:

      --export          Output default content (ignores PRIME.md override)
      --full            Force full CLI output (ignore MCP detection)
      --mcp             Force MCP mode (minimal output)
      --memories-only   Output only persistent memories for compact hook contexts
      --stealth         Stealth mode (no git operations, flush only)

bd quickstart

Display a quick start guide showing common bd workflows and patterns.

bd quickstart

bd recall

Retrieve the full content of a memory by its key.

Examples: bd recall dolt-phantoms bd recall auth-jwt

bd recall <key>

bd 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.

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 "<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

bd setup

Setup integration files for AI editors and coding assistants.

Recipes define where beads workflow instructions are written. Built-in recipes include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.

Examples: bd setup cursor # Install Cursor IDE integration bd setup codex # Install Codex skill + AGENTS.md guidance bd setup codex --global # Install global Codex skill + global AGENTS.md guidance 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 <recipe> --check' to verify installation status. Use 'bd setup <recipe> --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/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md)
      --list            List all available recipes
  -o, --output string   Write template to custom path
      --print           Print the template to stdout
      --project         Install for this project only (gemini/mux)
      --remove          Remove the integration
      --stealth         Use stealth mode (claude/gemini)

bd where

Show the active beads database location, including redirect information.

This command is useful for debugging when using redirects, to understand
which beads workspace is actually being used.

Examples: bd where # Show active beads location bd where --json # Output in JSON format

bd where

Maintenance:

bd 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 <id> [reason...] update <id> <key>=<value> [<key>=<value> ...] create <type> <priority> <title...> dep add <from-id> <to-id> [type] dep remove <from-id> <to-id> #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 '{print "close",$1," stale"}' | 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>')

bd 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

bd 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.<check-slug> 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.<slug>

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 JSONL (source of truth) 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)

bd 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

bd 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

bd 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 sync Set up sync.branch workflow for multi-clone setups

bd migrate [flags]

Flags:

      --dry-run          Show what would be done without making changes
      --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 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

bd 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

bd 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 (not yet implemented)
      --json        Output results as JSON
      --skip-lint   Skip lint check explicitly

bd 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.

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 >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)
      --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-*')

bd 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-*)

bd 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

bd rules

Audit and compact Claude rules

bd rules

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/")

bd 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

bd upgrade

Commands for checking bd version upgrades and reviewing changes.

The upgrade command helps you stay aware of bd version changes:

• bd upgrade status: Check if bd version changed since last use
• bd upgrade review: Show what's new since your last version
• bd upgrade ack: Acknowledge the current version

Version tracking is automatic - bd updates metadata.json on every run.

bd upgrade

bd upgrade ack

Mark the current bd version as acknowledged.

This updates metadata.json to record that you've seen the current version. Mainly useful after reviewing upgrade changes to suppress future upgrade notifications.

Note: Version tracking happens automatically, so you don't need to run this command unless you want to explicitly mark acknowledgement.

Examples: bd upgrade ack bd upgrade ack --json

bd upgrade ack

bd upgrade review

Show what's new in bd since the last version you used.

Unlike 'bd info --whats-new' which shows the last 3 versions, this command shows ALL changes since your specific last version.

If you're upgrading from an old version, you'll see the complete changelog of everything that changed since then.

Examples: bd upgrade review bd upgrade review --json

bd upgrade review

bd upgrade status

Check if bd has been upgraded since you last used it.

This command uses the version tracking that happens automatically at startup to detect if bd was upgraded.

Examples: bd upgrade status bd upgrade status --json

bd upgrade status

bd worktree

Manage git worktrees with proper beads configuration.

Worktrees allow multiple working directories sharing the same git repository, enabling parallel development (e.g., multiple agents or features).

Worktrees automatically share the same beads database as the main repository via git common directory discovery — no manual redirect configuration needed.

Examples: bd worktree create feature-auth # Create worktree bd worktree create bugfix --branch fix-1 # Create with specific branch name bd worktree list # List all worktrees bd worktree remove feature-auth # Remove worktree (with safety checks) bd worktree info # Show info about current worktree

bd worktree

bd worktree create

Create a git worktree for parallel development.

This command:

1. Creates a git worktree at ./<name> (or specified path)
2. Adds the worktree path to .gitignore (if inside repo root)

The worktree automatically shares the same beads database as the main repository via git common directory discovery — no redirect file needed.

Examples: bd worktree create feature-auth # Create at ./feature-auth bd worktree create bugfix --branch fix-1 # Create with branch name bd worktree create ../agents/worker-1 # Create at relative path

bd worktree create <name> [--branch=<branch>] [flags]

Flags:

      --branch string   Branch name for the worktree (default: same as name)

bd worktree info

Show information about the current worktree.

If the current directory is in a git worktree, shows:

• Worktree path and name
• Branch
• Beads configuration (redirect or main)
• Main repository location

Examples: bd worktree info # Show current worktree info bd worktree info --json # JSON output

bd worktree info

bd worktree list

List all git worktrees and their beads configuration state.

Shows each worktree with:

• Name (directory name)
• Path (full path)
• Branch
• Beads state: "redirect" (uses shared db), "shared" (is main), "none" (no beads)

Examples: bd worktree list # List all worktrees bd worktree list --json # JSON output

bd worktree list

bd worktree remove

Remove a git worktree with safety checks.

Before removing, this command checks for:

• Uncommitted changes
• Unpushed commits
• Stashes

Use --force to skip safety checks (not recommended).

Examples: bd worktree remove feature-auth # Remove with safety checks bd worktree remove feature-auth --force # Skip safety checks

bd worktree remove <name> [flags]

Flags:

      --force   Skip safety checks

Integrations & Advanced:

bd 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

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 -> 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, 95% reduction)

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 - < 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 (1 or 2) (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)

bd 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 "[email protected]" # 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

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 <refs>

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 <ids>

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

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")

bd 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 > LINEAR_API_KEY > 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 -> Backlog bd config set linear.priority_map.1 0 # Urgent -> Critical bd config set linear.priority_map.2 1 # High -> High bd config set linear.priority_map.3 2 # Medium -> Medium bd config set linear.priority_map.4 3 # Low -> 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

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 <refs>

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 <ids>

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

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

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

bd 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

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

Other Commands:

bd 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

bd ado projects

List Azure DevOps projects that the configured token has access to.

bd ado projects

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 <refs>

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 <ids>

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

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")

bd 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

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)

bd blocked

Show blocked issues

bd blocked [flags]

Flags:

      --parent string   Filter to descendants of this bead/epic

bd 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

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 <(bd completion bash)

To load completions for every new session, execute once:

Linux:

bd completion bash > /etc/bash_completion.d/bd

macOS:

bd completion bash > $(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 > ~/.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" >> ~/.zshrc

To load completions in your current shell session:

source <(bd completion zsh)

To load completions for every new session, execute once:

Linux:

bd completion zsh > "${fpath[1]}/_bd"

macOS:

bd completion zsh > $(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

bd 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 {{variable}} 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 {{vars}} 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

bd 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 bd-def # Defer multiple issues

bd defer [id...] [flags]

Flags:

      --until string   Defer until specific time (e.g., +1h, tomorrow, next monday)

bd formula

Manage workflow formulas - the source layer for molecule templates.

Formulas are YAML/JSON files that define workflows with composition rules. They are "cooked" into proto beads which can then be poured or wisped.

The Rig → Cook → Run lifecycle:

• Rig: Compose formulas (extends, compose)
• Cook: Transform to proto (bd cook expands macros, applies aspects)
• Run: Agents execute poured mols or wisps

Search paths (in order):

1. <resolved-beads-dir>/formulas/ (active project)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)

Commands: list List available formulas from all search paths show Show formula details, steps, and composition rules

bd formula

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. <resolved-beads-dir>/formulas/ (active project - highest priority)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)

Formulas in earlier paths shadow those with the same name in later paths.

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 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

Examples: bd formula show shiny bd formula show rule-of-five bd formula show security-audit --json

bd formula show <formula-name>

bd 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

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 <refs>

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 <ids>

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

bd github status

Display current GitHub configuration and sync status.

bd github status

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

bd 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

bd gitlab projects

List GitLab projects that the configured token has access to.

bd gitlab projects

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 <refs>

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 <ids>

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

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')

bd help

Help provides help for any command in the application. Simply type bd help [path to command] for full details.

bd help [command] [flags]

Flags:

      --all          Show help for all commands in a single document
      --doc string   Generate markdown docs for a single command
  -h, --help         help for help
      --list         List all available commands

bd 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.

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-<issue-prefix>

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 passed --force/--reinit-local 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

bd 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...]

bd 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 ({{key}}) 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

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-{{worker_name}} --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-{{name}} --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 (>100 steps), a summary is shown instead. Use --limit or --range to view specific steps: bd mol current <id> --limit 50 # Show first 50 steps bd mol current <id> --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 {{variable}} 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. <resolved-beads-dir>/formulas/ (project-level, default)
2. <checkout-root>/.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>

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) -> pour -> 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]

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

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. <resolved-beads-dir>/formulas/ (active project)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, 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 <proto> or bd create --ephemeral
2. Execute: Normal bd operations work on wisp issues
3. Squash: bd mol squash <id> (clears Ephemeral flag, promotes to persistent)
4. Or burn: bd mol burn <id> (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) -> 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)

bd notion

Commands for syncing issues between beads and Notion.

bd notion

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 <refs>

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 <ids>

bd notion push [bead-ids...] [flags]

Flags:

      --dry-run   Preview push without making changes

bd notion status

Show Notion sync status

bd notion status

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")

bd 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

bd 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
      --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

bd 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>

bd ship

Ship a capability to satisfy cross-project dependencies.

This command:

1. Finds issue with export:<capability> label
2. Validates issue is closed (or --force to override)
3. Adds provides:<capability> label

External projects can depend on this capability using: bd dep add <issue> external:<project>:<capability>

The capability is resolved when the external project has a closed issue with the provides:<capability> 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

bd undefer

Undefer issues to restore them to open status.

This brings issues back from the icebox so they can be worked on again. Issues will appear in 'bd ready' if they have no blockers.

Examples: bd undefer bd-abc # Undefer a single issue bd undefer bd-abc bd-def # Undefer multiple issues

bd undefer [id...]

bd version

Print version information

bd version