CLI Reference
Complete reference for all bd commands.
Command Structure
bd [global-flags] <command> [command-flags] [arguments]
Global Flags
| Flag | Description |
|---|---|
--db <path> | Use specific database file |
--no-daemon | Bypass daemon, direct database access |
--json | Output in JSON format |
--quiet | Suppress non-essential output |
--verbose | Verbose output |
--version | Show version |
--help | Show help |
Command Categories
Essential Commands
Most frequently used:
| Command | Description |
|---|---|
bd create | Create new issue |
bd list | List issues with filters |
bd show | Show issue details |
bd update | Update issue fields |
bd close | Close an issue |
bd ready | Show unblocked work |
bd sync | Force sync to git |
Issue Management
| Command | Description |
|---|---|
bd create | Create issue |
bd show | Show details |
bd update | Update fields |
bd close | Close issue |
bd delete | Delete issue |
bd reopen | Reopen closed issue |
Dependencies
| Command | Description |
|---|---|
bd dep add | Add dependency |
bd dep remove | Remove dependency |
bd dep tree | Show dependency tree |
bd dep cycles | Detect circular dependencies |
bd blocked | Show blocked issues |
bd ready | Show unblocked issues |
Labels & Comments
| Command | Description |
|---|---|
bd label add | Add label to issue |
bd label remove | Remove label |
bd label list | List all labels |
bd comment add | Add comment |
bd comment list | List comments |
Sync & Export
| Command | Description |
|---|---|
bd sync | Full sync cycle |
bd export | Export to JSONL |
bd import | Import from JSONL |
bd migrate | Migrate database schema |
System
| Command | Description |
|---|---|
bd init | Initialize beads in project |
bd info | Show system info |
bd version | Show version |
bd config | Manage configuration |
bd daemons | Manage daemons |
bd hooks | Manage git hooks |
Workflows
| Command | Description |
|---|---|
bd pour | Instantiate formula as molecule |
bd wisp | Create ephemeral wisp |
bd mol | Manage molecules |
bd pin | Pin work to agent |
bd hook | Show pinned work |
Quick Reference
Creating Issues
# Basic
bd create "Title" -t task -p 2
# With description
bd create "Title" --description="Details here" -t bug -p 1
# With labels
bd create "Title" -l "backend,urgent"
# As child of epic
bd create "Subtask" --parent bd-42
# With discovered-from link
bd create "Found bug" --deps discovered-from:bd-42
# JSON output
bd create "Title" --json
Querying Issues
# All open issues
bd list --status open
# High priority bugs
bd list --status open --priority 0,1 --type bug
# With specific labels
bd list --label-any urgent,critical
# JSON output
bd list --json
Working with Dependencies
# Add: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View tree
bd dep tree bd-2
# Find cycles
bd dep cycles
# What's ready to work?
bd ready
# What's blocked?
bd blocked
Syncing
# Full sync (export + commit + push)
bd sync
# Force export
bd export
# Import from file
bd import -i .beads/issues.jsonl