beads/examples/claude-code-skill/references/CLI_REFERENCE.md

CLI Reference

Complete command reference for bd (beads) CLI tool. All commands support --json flag for structured output.

Contents

• Quick Reference
• Global Flags
• Core Commands
  • bd ready - Find unblocked work
  • bd create - Create new issues
  • bd update - Update issue status, priority, assignee
  • bd close - Close completed work
  • bd show - Show issue details
  • bd list - List issues with filters
• Dependency Commands
  • bd dep add - Create dependencies
  • bd dep tree - Visualize dependency trees
  • bd dep cycles - Detect circular dependencies
• Monitoring Commands
  • bd stats - Project statistics
  • bd blocked - Find blocked work
• Data Management Commands
  • bd export - Export database to JSONL
  • bd import - Import issues from JSONL
• Setup Commands
  • bd init - Initialize database
  • bd quickstart - Show quick start guide
• Common Workflows
• JSON Output
• Database Auto-Discovery
• Git Integration
• Tips

Quick Reference

Command	Purpose	Key Flags
bd ready	Find unblocked work	--priority, --assignee, --limit, --json
bd list	List all issues with filters	--status, --priority, --type, --assignee
bd show	Show issue details	--json
bd create	Create new issue	-t, -p, -d, --design, --acceptance
bd update	Update existing issue	--status, --priority, --design
bd close	Close completed issue	--reason
bd dep add	Add dependency	--type (blocks, related, parent-child, discovered-from)
bd dep tree	Visualize dependency tree	(no flags)
bd dep cycles	Detect circular dependencies	(no flags)
bd stats	Get project statistics	--json
bd blocked	Find blocked issues	--json
bd export	Export issues to JSONL	--json
bd import	Import issues from JSONL	--resolve-collisions
bd init	Initialize bd in directory	--prefix
bd quickstart	Show quick start guide	(no flags)

Global Flags

Available for all commands:

--json                 # Output in JSON format
--db /path/to/db       # Specify database path (default: auto-discover)
--actor "name"         # Actor name for audit trail
--no-auto-flush        # Disable automatic JSONL sync
--no-auto-import       # Disable automatic JSONL import

Core Commands

bd ready

Find tasks with no blockers - ready to be worked on.

bd ready                      # All ready work
bd ready --json               # JSON format
bd ready --priority 0         # Only priority 0 (critical)
bd ready --assignee alice     # Only assigned to alice
bd ready --limit 5            # Limit to 5 results

Use at session start to see available work.

---

bd create

Create a new issue with optional metadata.

bd create "Title"
bd create "Title" -t bug -p 0
bd create "Title" -d "Description"
bd create "Title" --design "Design notes"
bd create "Title" --acceptance "Definition of done"
bd create "Title" --assignee alice

Flags:

• -t, --type: task (default), bug, feature, epic, chore
• -p, --priority: 0-3 (default: 2)
• -d, --description: Issue description
• --design: Design notes
• --acceptance: Acceptance criteria
• --assignee: Who should work on this

---

bd update

Update an existing issue's metadata.

bd update issue-123 --status in_progress
bd update issue-123 --priority 0
bd update issue-123 --design "Decided to use Redis"
bd update issue-123 --acceptance "Tests passing"

Status values: open, in_progress, blocked, closed

---

bd close

Close (complete) an issue.

bd close issue-123
bd close issue-123 --reason "Implemented in PR #42"
bd close issue-1 issue-2 issue-3 --reason "Bulk close"

Note: Closed issues remain in database for history.

---

bd show

Show detailed information about a specific issue.

bd show issue-123
bd show issue-123 --json

Shows: all fields, dependencies, dependents, audit history.

---

bd list

List all issues with optional filters.

bd list                          # All issues
bd list --status open            # Only open
bd list --priority 0             # Critical
bd list --type bug               # Only bugs
bd list --assignee alice         # By assignee
bd list --status closed --limit 10  # Recent completions

---

Dependency Commands

bd dep add

Add a dependency between issues.

bd dep add from-issue to-issue                      # blocks (default)
bd dep add from-issue to-issue --type blocks
bd dep add from-issue to-issue --type related
bd dep add epic-id task-id --type parent-child
bd dep add original-id found-id --type discovered-from

Dependency types:

1. blocks: from-issue blocks to-issue (hard blocker)
2. related: Soft link (no blocking)
3. parent-child: Epic/subtask hierarchy
4. discovered-from: Tracks origin of discovery

---

bd dep tree

Visualize full dependency tree for an issue.

bd dep tree issue-123

Shows all dependencies and dependents in tree format.

---

bd dep cycles

Detect circular dependencies.

bd dep cycles

Finds dependency cycles that would prevent work from being ready.

---

Monitoring Commands

bd stats

Get project statistics.

bd stats
bd stats --json

Returns: total, open, in_progress, closed, blocked, ready, avg lead time.

---

bd blocked

Get blocked issues with blocker information.

bd blocked
bd blocked --json

Use to identify bottlenecks when ready list is empty.

---

Data Management Commands

bd export

Export all issues to JSONL format.

bd export > issues.jsonl
bd export --json  # Same output, explicit flag

Use cases:

• Manual backup before risky operations
• Sharing issues across databases
• Version control / git tracking
• Data migration or analysis

Note: bd auto-exports to .beads/*.jsonl after each operation (5s debounce). Manual export is rarely needed.

---

bd import

Import issues from JSONL format.

bd import < issues.jsonl
bd import --resolve-collisions < issues.jsonl

Flags:

• --resolve-collisions - Automatically remap conflicting issue IDs

Use cases for --resolve-collisions:

• Reimporting after manual JSONL edits - if you closed an issue in the JSONL that's still open in DB
• Merging databases - importing issues from another database with overlapping IDs
• Restoring from backup - when database state has diverged from JSONL

What --resolve-collisions does:

1. Detects ID conflicts (same ID, different status/content)
2. Remaps conflicting imports to new IDs
3. Updates all references and dependencies to use new IDs
4. Reports remapping (e.g., "mit-1 → bd-4")

Without --resolve-collisions: Import fails on first conflict.

Example scenario:

# You have: mit-1 (open) in database
# Importing: mit-1 (closed) from JSONL
# Result: Import creates bd-4 with closed status, preserves existing mit-1

---

Setup Commands

bd init

Initialize bd in current directory.

bd init                    # Auto-detect prefix
bd init --prefix api       # Custom prefix

Creates .beads/ directory and database.

---

bd quickstart

Show comprehensive quick start guide.

bd quickstart

Displays built-in reference for command syntax and workflows.

---

Common Workflows

Session Start

bd ready --json
bd show issue-123
bd update issue-123 --status in_progress

Discovery During Work

bd create "Found: bug in auth" -t bug
bd dep add current-issue new-issue --type discovered-from

Completing Work

bd close issue-123 --reason "Implemented with tests passing"
bd ready  # See what unblocked

Planning Epic

bd create "OAuth Integration" -t epic
bd create "Set up credentials" -t task
bd create "Implement flow" -t task

bd dep add oauth-epic oauth-creds --type parent-child
bd dep add oauth-epic oauth-flow --type parent-child
bd dep add oauth-creds oauth-flow  # creds blocks flow

bd dep tree oauth-epic

---

JSON Output

All commands support --json for structured output:

bd ready --json
bd show issue-123 --json
bd list --status open --json
bd stats --json

Use when parsing programmatically or extracting specific fields.

---

Database Auto-Discovery

bd finds database in this order:

1. --db flag: bd ready --db /path/to/db.db
2. $BEADS_DB environment variable
3. .beads/*.db in current directory or ancestors
4. ~/.beads/default.db as fallback

Project-local (.beads/): Project-specific work, git-tracked

Global fallback (~/.beads/): Cross-project tracking, personal tasks

---

Git Integration

bd automatically syncs with git:

• After each operation: Exports to JSONL (5s debounce)
• After git pull: Imports from JSONL if newer than DB

Files:

• .beads/*.jsonl - Source of truth (git-tracked)
• .beads/*.db - Local cache (gitignored)

Git Integration Troubleshooting

Problem: .gitignore ignores entire .beads/ directory

Symptom: JSONL file not tracked in git, can't commit beads

Cause: Incorrect .gitignore pattern blocks everything

Fix:

# Check .gitignore
cat .gitignore | grep beads

# ❌ WRONG (ignores everything including JSONL):
.beads/

# ✅ CORRECT (ignores only SQLite cache):
.beads/*.db
.beads/*.db-*

After fixing: Remove the .beads/ line and add the specific patterns. Then git add .beads/issues.jsonl.

---

Permission Troubleshooting

Problem: bd commands prompt for permission despite whitelist

Symptom: bd commands ask for confirmation even with Bash(bd:*) in settings.local.json

Root Cause: Wildcard patterns in settings.local.json don't actually work - not for bd, not for git, not for any Bash commands. This is a general Claude Code limitation, not bd-specific.

How It Actually Works:

• Individual command approvals (like Bash(bd ready)) DO persist across sessions
• These are stored server-side by Claude Code, not in local config files
• Commands like git status work without prompting because they've been individually approved many times, creating the illusion of a working wildcard pattern

Permanent Solution:

1. Trigger each bd subcommand you use frequently (see command list below)
2. When prompted, click "Yes, and don't ask again" (NOT "Allow this time")
3. That specific command will be permanently approved across all future sessions

Common bd Commands to Approve:

bd ready
bd list
bd stats
bd blocked
bd export
bd version
bd quickstart
bd dep cycles
bd --help
bd [command] --help  # For any subcommand help

Note: Dynamic commands with arguments (like bd show <issue-id>, bd create "title") must be approved per-use since arguments vary. Only static commands can be permanently whitelisted.

---

Tips

Use JSON for parsing:

bd ready --json | jq '.[0].id'

Bulk operations:

bd close issue-1 issue-2 issue-3 --reason "Sprint complete"

Quick filtering:

bd list --status open --priority 0 --type bug

Built-in help:

bd quickstart       # Comprehensive guide
bd create --help    # Command-specific help