beads/website/versioned_docs/version-1.0.0/getting-started/quickstart.md
matt wilkie b2a4d1d04a
docs: generate CLI reference from live help (#3704)
* docs: generate CLI reference from live help

* docs(cli): move bd version stamp from per-command pages to index only

Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:

- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
  labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
  labelled with the explicit semver tag parsed from the directory name

This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.

Refs: mybd-afb, PR #3704

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 19:43:49 -07:00

3 KiB

id title sidebar_position
quickstart Quick Start 2

Beads Quick Start

Get up and running with beads in a few minutes.

Why Beads?

Flat issue trackers show you all open items. You pick one - but if it depends on something else that isn't done yet, you've wasted time. Beads tracks dependencies between issues and computes a ready queue - only items with no active blockers appear.

$ bd ready
1. [P1] [task] bd-1: Set up database

$ bd ready --explain --json | jq '.blocked[0]'
{
  "id": "bd-3",
  "title": "Add authentication",
  "blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}

The agent picks the right task every time.

Initialize

cd your-project
bd init          # Interactive setup (prompts for role)
bd init --quiet  # Non-interactive (for AI agents)

The wizard creates .beads/, sets up the embedded Dolt database, and optionally installs git hooks. During init, you'll be asked whether you're a maintainer or contributor - this determines how beads routes issues. You can change it later with git config beads.role.

Create Issues and Dependencies

# Create issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature

# Add dependencies (API needs database, auth needs API)
bd dep add bd-2 bd-1
bd dep add bd-3 bd-2

# View the dependency tree
bd dep tree bd-3

Issue IDs are hash-based (e.g., bd-a1b2) to prevent collisions when multiple agents work concurrently.

Find and Work the Ready Queue

# What's unblocked right now?
bd ready

# Why is something blocked?
bd ready --explain

# Claim and complete work
bd update bd-1 --claim
bd close bd-1 --reason "Database setup complete"

# Now bd-2 is ready
bd ready

bd ready is not the same as bd list --status open - the list command shows all open issues regardless of blockers. The ready command computes the dependency graph and only shows truly unblocked work.

Epics

Group related work under an epic:

bd create "Auth System" -t epic -p 1       # Returns: bd-a3f8e9
bd create "Design login UI" -p 1 --parent bd-a3f8e9
bd create "Backend validation" -p 1 --parent bd-a3f8e9
bd dep tree bd-a3f8e9

Team Sync

Share issues using Dolt remotes (works over the same Git remote):

bd dolt remote add origin git+ssh://git@github.com/org/repo.git
bd dolt push
bd dolt pull

When a teammate clones the repo, bd bootstrap auto-detects the existing database. See bd dolt for sync commands.

Track Progress

bd blocked    # See blocked issues
bd stats      # Project statistics
bd list       # All issues
bd doctor     # Health check

Next Steps

  • Add labels: bd create "Task" -l "backend,urgent"
  • Filter ready work: bd ready --priority 1
  • Check graph integrity: bd graph check
  • Gates for PR/CI sync: bd gate
  • IDE integration: IDE Setup
  • Full command list: CLI Reference