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

# Limit tree depth (default: 50)
bd dep tree issue-123 --max-depth 10
bd dep tree issue-123 -d 10

Shows all dependencies and dependents in tree format. Use --max-depth to limit traversal depth for very deep trees.

---

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.

---

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)

---

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