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>
231 lines
6.5 KiB
Markdown
231 lines
6.5 KiB
Markdown
---
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bd close <id> # Close issue
|
|
bd close <id> --continue # Auto-advance to next step
|
|
bd close <id> --suggest-next # Show newly unblocked
|
|
```
|
|
|
|
## Finding Work
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bd dep list <id> # Show dependencies
|
|
bd dep tree <id> # Dependency tree
|
|
bd dep cycles # Detect cycles
|
|
```
|
|
|
|
### Removing Dependencies
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 |
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 |
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bd update <id> --status=in_progress
|
|
# ... do work ...
|
|
bd close <id>
|
|
```
|
|
|
|
### Creating Related Issues
|
|
|
|
```bash
|
|
bd create "Main task" --deps "blocks:<other-id>"
|
|
bd dep add <new-id> <blocker-id>
|
|
```
|
|
|
|
### Working Through a Molecule
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 doctor` if something seems wrong
|