beads/website/docs/cli-reference/index.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

3.7 KiB

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
--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 dolt push Push changes to Dolt remote
bd dolt pull Pull changes from Dolt remote

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 dolt push Push changes to Dolt remote
bd dolt pull Pull changes from Dolt remote
bd export Export data to 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 doctor Check system health
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

# Push changes to Dolt remote
bd dolt push

# Pull changes from Dolt remote
bd dolt pull

# Export to file
bd export -o backup.jsonl

See Also