* 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>
115 lines
3 KiB
Markdown
115 lines
3 KiB
Markdown
---
|
|
id: quickstart
|
|
title: Quick Start
|
|
sidebar_position: 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.
|
|
|
|
```bash
|
|
$ 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`](/cli-reference/dolt) for sync commands.
|
|
|
|
## Track Progress
|
|
|
|
```bash
|
|
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`](/cli-reference/gate)
|
|
- IDE integration: [IDE Setup](/getting-started/ide-setup)
|
|
- Full command list: [CLI Reference](/cli-reference)
|