John Ogle
f472aa9b3d
All checks were successful
CI / check (push) Successful in 3m23s
Comprehensive bd CLI reference covering: - Core commands (create, update, close, show, list) - Dependency management (bd dep add, bd blocked) - Formula/molecule workflow (pour, wisp, cook, gates) - When to use bd vs TodoWrite Complements existing beads_workflow.md which covers philosophy and humanlayer integration patterns. Closes: nixos-configs-6pk Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
6.5 KiB
6.5 KiB
description
| description |
|---|
| How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration |
BD Workflow
The bd CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction.
When to Use BD vs TodoWrite
| Use BD | Use TodoWrite |
|---|---|
| Work spans multiple sessions | Single-session tasks |
| Dependencies between tasks | Independent subtasks |
| Need audit trail in git | Ephemeral tracking |
| Cross-repo coordination | Local project only |
| Resuming after compaction | Simple task lists |
Core Commands
Creating Issues
bd create "Issue title" # Basic task
bd create "Bug title" --type=bug --priority=1 # P1 bug
bd create "Feature" --type=feature -d "Details" # With description
bd q "Quick capture" # Output only ID
Managing Issues
bd show <id> # View issue details
bd show <id> --children # View children of epic
bd list # List open issues (default 50)
bd list --all # Include closed
bd list -s in_progress # Filter by status
bd list -t bug -p 0 # P0 bugs
bd list --pretty # Tree format
Updating Issues
bd update <id> --status=in_progress # Start work
bd update <id> --status=blocked # Mark blocked
bd update <id> --claim # Claim atomically
bd update <id> --add-label=urgent # Add label
bd update <id> -d "New description" # Update description
Closing Issues
bd close <id> # Close issue
bd close <id> --continue # Auto-advance to next step
bd close <id> --suggest-next # Show newly unblocked
Finding Work
bd ready # Ready issues (no blockers)
bd ready --mol <mol-id> # Ready steps in molecule
bd ready -n 5 # Limit to 5
bd ready --assignee me # Assigned to me
bd blocked # Show blocked issues
bd blocked --parent <id> # Blocked within epic
Dependency Management
Creating Dependencies
bd dep <blocker> --blocks <blocked> # A blocks B
bd dep add <blocked> <blocker> # Same as above
bd dep relate <id1> <id2> # Bidirectional link
Viewing Dependencies
bd dep list <id> # Show dependencies
bd dep tree <id> # Dependency tree
bd dep cycles # Detect cycles
Removing Dependencies
bd dep remove <blocked> <blocker> # Remove dependency
bd dep unrelate <id1> <id2> # Remove relation
Sync Workflow
BD syncs issues via git. The daemon handles this automatically, but manual sync is available:
bd sync # Full sync (pull, merge, push)
bd sync --flush-only # Export to JSONL only
bd sync --import-only # Import from JSONL only
bd sync --status # Show sync branch diff
bd sync --squash # Accumulate without commit
Formula and Molecule Workflow
Formulas are reusable workflow templates. Molecules are instantiated workflows.
Formulas
bd formula list # List available formulas
bd formula list --type=workflow # Filter by type
bd formula show <name> # Show formula details
bd cook <formula> # Compile to proto (stdout)
bd cook <formula> --var name=auth # With variable substitution
bd cook <formula> --dry-run # Preview steps
bd cook <formula> --persist # Save to database
Molecules: Pour vs Wisp
| pour (persistent) | wisp (ephemeral) |
|---|---|
| Feature implementations | Release workflows |
| Multi-session work | Patrol cycles |
| Audit trail needed | Health checks |
| Git-synced | Local only |
# Persistent molecule (liquid phase)
bd mol pour <proto> --var name=auth
# Ephemeral molecule (vapor phase)
bd mol wisp <proto> --var version=1.0
bd mol wisp list # List wisps
bd mol wisp gc # Garbage collect
Tracking Molecule Progress
bd mol show <mol-id> # Show structure
bd mol show <mol-id> --parallel # Parallelizable steps
bd mol current # Where am I?
bd mol current <mol-id> # Status for molecule
bd mol progress <mol-id> # Progress summary + ETA
Molecule Lifecycle
bd mol squash <mol-id> # Condense to digest
bd mol burn <mol-id> # Delete wisp
bd mol distill <epic-id> # Extract formula from epic
Gates and Human Checkpoints
Gates are async wait conditions that block workflow steps:
| Gate Type | Wait Condition |
|---|---|
| human | Manual bd close |
| timer | Timeout expires |
| gh:run | GitHub workflow completes |
| gh:pr | PR merges |
| bead | Cross-rig bead closes |
bd gate list # Show open gates
bd gate list --all # Include closed
bd gate check # Evaluate all gates
bd gate check --type=bead # Check bead gates only
bd gate resolve <id> # Close manually
Common Patterns
Starting Work on a Bead
bd update <id> --status=in_progress
# ... do work ...
bd close <id>
Creating Related Issues
bd create "Main task" --deps "blocks:<other-id>"
bd dep add <new-id> <blocker-id>
Working Through a Molecule
bd mol pour my-workflow --var name=feature
bd ready --mol <mol-id> # Find next step
bd update <step-id> --claim # Claim step
# ... do work ...
bd close <step-id> --continue # Close and advance
Quick Status Check
bd ready -n 3 # Top 3 ready items
bd list -s in_progress # What's in flight?
bd blocked # What's stuck?
Useful Flags
| Flag | Effect |
|---|---|
--json |
JSON output for scripting |
--quiet |
Suppress non-essential output |
--dry-run |
Preview without executing |
--pretty |
Tree format display |
Integration Notes
- BD auto-syncs via daemon (check with
bd info) - Issues stored in
.beads/directory - JSONL files sync through git
- Use
bd doctorif something seems wrong