beads/website/docs/cli-reference/essential.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.5 KiB

id title sidebar_position
essential Essential Commands 2

Essential Commands

The most important commands for daily use.

bd create

Create a new issue.

bd create <title> [flags]

Flags:

Flag Short Description
--type -t Issue type: bug, feature, task, epic, chore
--priority -p Priority: 0-4 (0=critical, 4=backlog)
--description -d Detailed description
--labels -l Comma-separated labels
--parent Parent issue ID (for hierarchical)
--deps Dependencies (e.g., discovered-from:bd-42)
--json JSON output

Examples:

bd create "Fix login bug" -t bug -p 1
bd create "Add dark mode" -t feature -p 2 --description="User requested"
bd create "Subtask" --parent bd-42 -p 2
bd create "Found during work" --deps discovered-from:bd-42 --json

bd list

List issues with filters.

bd list [flags]

Flags:

Flag Description
--status Filter by status: open, in_progress, closed
--priority Filter by priority (comma-separated)
--type Filter by type (comma-separated)
--label-any Issues with any of these labels
--label-all Issues with all of these labels
--json JSON output

Examples:

bd list --status open
bd list --priority 0,1 --type bug
bd list --label-any urgent,critical --json

bd show

Show issue details.

bd show <id> [flags]

Examples:

bd show bd-42
bd show bd-42 --json
bd show bd-42 bd-43 bd-44  # Multiple issues

bd update

Update issue fields.

bd update <id> [flags]

Flags:

Flag Description
--status New status
--priority New priority
--title New title
--description New description
--add-label Add label
--remove-label Remove label
--json JSON output

Examples:

bd update bd-42 --claim
bd update bd-42 --priority 0 --add-label urgent
bd update bd-42 --title "Updated title" --json

bd close

Close an issue.

bd close <id> [flags]

Flags:

Flag Description
--reason Closure reason
--json JSON output

Examples:

bd close bd-42
bd close bd-42 --reason "Fixed in PR #123"
bd close bd-42 --json

bd ready

Show issues ready to work on (no blockers).

bd ready [flags]

Flags:

Flag Description
--priority Filter by priority
--type Filter by type
--json JSON output

Examples:

bd ready
bd ready --priority 1
bd ready --json

bd blocked

Show blocked issues and their blockers.

bd blocked [flags]

Examples:

bd blocked
bd blocked --json

bd dolt push

Push changes to a Dolt remote.

bd dolt push [flags]

Performs:

  1. Dolt commit (snapshot current database state)
  2. Push to Dolt remote

Examples:

bd dolt push

bd dolt pull

Pull changes from a Dolt remote.

bd dolt pull [flags]

Examples:

bd dolt pull

bd info

Show system information.

bd info [flags]

Flags:

Flag Description
--whats-new Show recent version changes
--schema Show database schema
--json JSON output

Examples:

bd info
bd info --whats-new
bd info --json

bd stats

Show project statistics.

bd stats [flags]

Examples:

bd stats
bd stats --json