Apply findings from docs/GETTING_STARTED_ANALYSIS.md: - installation.md (261->81): Remove IDE section (duplicates ide-setup.md), remove updating section (duplicates upgrading.md), consolidate platforms, move CGO/build deps below happy path - quickstart.md (370->115): Remove Notion sync, database maintenance, database migration, database location sections. Trim role config and init options. Keep core flow: init, create, deps, ready, work, sync - ide-setup.md (204->80): Remove bd prime internals, trim MCP duplication, condense per-editor sections to command + verify pattern - upgrading.md (135->39): Consolidate table with detailed sections, trim troubleshooting to essentials Total: 970 lines -> 315 lines (3.1x reduction) Closes #3245
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 [Sync](/cli-reference/sync) for details.
|
|
|
|
## 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: [Dependencies](/cli-reference/dependencies)
|
|
- IDE integration: [IDE Setup](/getting-started/ide-setup)
|
|
- Full command list: [CLI Reference](/cli-reference)
|