beads/website/docs/cli-reference/index.md

id, title, sidebar_position

id	title	sidebar_position
index	CLI Reference	1

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

See Also

• Essential Commands
• Issue Commands
• Dependency Commands
• Label Commands
• Sync Commands