* fix(init): wire git origin as Dolt remote Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync. Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only. _codex-gpt-5-xhigh on behalf of maphew_ * test: keep embedded command stderr out of parsed stdout Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_ --------- Co-authored-by: CI Bot <ci@beads.test>
371 lines
9.8 KiB
Markdown
371 lines
9.8 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 (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
|
|
|
|
Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:
|
|
|
|
**Flat tracker (GitHub Issues):**
|
|
```
|
|
Open issues: Set up database, Create API, Add authentication
|
|
→ An agent picks "Add authentication" and gets stuck immediately
|
|
```
|
|
|
|
**Beads:**
|
|
```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. No wasted cycles.
|
|
|
|
## Installation
|
|
|
|
Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).
|
|
|
|
**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.
|
|
|
|
```bash
|
|
bd --help
|
|
```
|
|
|
|
## Initialize
|
|
|
|
First time in a repository:
|
|
|
|
```bash
|
|
# Basic setup (prompts for contributor mode)
|
|
bd init
|
|
|
|
# For AI agents (non-interactive)
|
|
bd init --quiet
|
|
|
|
# OSS contributor (fork workflow with separate planning repo)
|
|
bd init --contributor
|
|
|
|
# Team member (branch workflow for collaboration)
|
|
bd init --team
|
|
|
|
# Protected main branch (GitHub/GitLab)
|
|
# Note: Dolt stores data under refs/dolt/data, separate from
|
|
# Git refs, so no --branch flag is needed.
|
|
```
|
|
|
|
The wizard will:
|
|
- Create `.beads/` directory and embedded Dolt database
|
|
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
|
|
- Import existing issues from git (if any)
|
|
- Prompt to install git hooks (recommended)
|
|
- Prompt to configure git merge driver (recommended)
|
|
|
|
Notes:
|
|
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
|
|
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
|
|
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
|
|
- To import issues from an older installation, run `bd init --from-jsonl`.
|
|
|
|
### Role configuration
|
|
|
|
During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"
|
|
|
|
- Answer **Y** if you're contributing to a fork (runs contributor wizard)
|
|
- Answer **N** if you're the maintainer or have push access
|
|
|
|
This sets `git config beads.role` which determines how beads routes issues:
|
|
|
|
| Role | Use case | Issue storage |
|
|
|------|----------|---------------|
|
|
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
|
|
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
|
|
|
|
You can also configure manually:
|
|
|
|
```bash
|
|
# Set as contributor
|
|
git config beads.role contributor
|
|
|
|
# Set as maintainer
|
|
git config beads.role maintainer
|
|
|
|
# Check current role
|
|
git config --get beads.role
|
|
```
|
|
|
|
**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.
|
|
|
|
## Your first issues
|
|
|
|
```bash
|
|
# Create a few 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
|
|
|
|
# List them
|
|
bd list
|
|
```
|
|
|
|
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
|
|
|
|
## Hierarchical issues (epics)
|
|
|
|
For large features, use hierarchical IDs to organize work:
|
|
|
|
```bash
|
|
# Create epic (generates parent hash ID)
|
|
bd create "Auth System" -t epic -p 1
|
|
# Returns: bd-a3f8e9
|
|
|
|
# Create child tasks (use --parent to attach to the epic)
|
|
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
|
|
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
|
|
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
|
|
|
|
# View hierarchy
|
|
bd dep tree bd-a3f8e9
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Dependency tree for bd-a3f8e9:
|
|
|
|
> bd-a3f8e9: Auth System [epic] [P1] (open)
|
|
> bd-a3f8e9.1: Design login UI [P1] (open)
|
|
> bd-a3f8e9.2: Backend validation [P1] (open)
|
|
> bd-a3f8e9.3: Integration tests [P1] (open)
|
|
```
|
|
|
|
## Add dependencies
|
|
|
|
```bash
|
|
# API depends on database
|
|
bd dep add bd-2 bd-1
|
|
|
|
# Auth depends on API
|
|
bd dep add bd-3 bd-2
|
|
|
|
# View the tree
|
|
bd dep tree bd-3
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Dependency tree for bd-3:
|
|
|
|
> bd-3: Add authentication [P2] (open)
|
|
> bd-2: Create API [P2] (open)
|
|
> bd-1: Set up database [P1] (open)
|
|
```
|
|
|
|
**Dependency visibility:** `bd list` shows blocking dependencies inline:
|
|
```
|
|
○ bd-a1b2 [P1] [task] - Set up database
|
|
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
|
|
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
|
|
```
|
|
|
|
## Find ready work
|
|
|
|
```bash
|
|
bd ready
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Ready work (1 issues with no blockers):
|
|
|
|
1. [P1] bd-1: Set up database
|
|
```
|
|
|
|
Only bd-1 is ready because bd-2 and bd-3 are blocked.
|
|
|
|
**Understanding why:** Use `--explain` to see the full graph reasoning:
|
|
|
|
```bash
|
|
bd ready --explain
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Ready Work Explanation
|
|
|
|
● Ready (1 issues):
|
|
|
|
bd-1 [P1] Set up database
|
|
Reason: no blocking dependencies
|
|
Unblocks: 1 issue(s)
|
|
|
|
● Blocked (2 issues):
|
|
|
|
bd-2 [P2] Create API
|
|
← blocked by bd-1: Set up database [open]
|
|
|
|
bd-3 [P2] Add authentication
|
|
← blocked by bd-2: Create API [open]
|
|
|
|
─ Summary: 1 ready, 2 blocked
|
|
```
|
|
|
|
**Note:** `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.
|
|
|
|
## Work the queue
|
|
|
|
```bash
|
|
# Start working on bd-1
|
|
bd update bd-1 --claim
|
|
|
|
# Complete it
|
|
bd close bd-1 --reason "Database setup complete"
|
|
|
|
# Check ready work again
|
|
bd ready
|
|
```
|
|
|
|
Now bd-2 is ready.
|
|
|
|
## Track progress
|
|
|
|
```bash
|
|
# See blocked issues
|
|
bd blocked
|
|
|
|
# View statistics
|
|
bd stats
|
|
```
|
|
|
|
## Team sync
|
|
|
|
Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs. In repos with `origin`, `bd init` configures that Dolt remote automatically.
|
|
|
|
```bash
|
|
# Verify the remote, or add one if the repo had no origin during init
|
|
bd dolt remote list
|
|
bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed
|
|
|
|
# Push your issues
|
|
bd dolt push
|
|
|
|
# Pull teammates' changes
|
|
bd dolt pull
|
|
```
|
|
|
|
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`.
|
|
|
|
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration and federation, see the repository docs [DOLT.md](https://github.com/gastownhall/beads/blob/main/docs/DOLT.md) and [FEDERATION-SETUP.md](https://github.com/gastownhall/beads/blob/main/FEDERATION-SETUP.md).
|
|
|
|
## Optional: Notion sync
|
|
|
|
If you keep project issues in Notion, save an integration token first:
|
|
|
|
```bash
|
|
bd config set notion.token <your-token>
|
|
```
|
|
|
|
Then either create a new Beads database under a parent page or connect to an existing target:
|
|
|
|
```bash
|
|
bd notion init --parent <page-id>
|
|
# or
|
|
bd notion connect --url <notion-database-or-data-source-url>
|
|
```
|
|
|
|
The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
|
|
|
|
Check which auth source is active and whether the target schema is ready:
|
|
|
|
```bash
|
|
bd notion status
|
|
bd notion status --json
|
|
```
|
|
|
|
Preview or run sync:
|
|
|
|
```bash
|
|
bd notion sync --dry-run
|
|
bd notion sync
|
|
bd notion sync --pull
|
|
bd notion sync --push
|
|
```
|
|
|
|
## Database location
|
|
|
|
By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
|
|
In server mode, data is managed by the external `dolt sql-server`.
|
|
|
|
## Migrating databases
|
|
|
|
After upgrading bd, use `bd migrate` to check for and migrate old database files:
|
|
|
|
```bash
|
|
# Inspect migration plan (AI agents)
|
|
bd migrate --inspect --json
|
|
|
|
# Check schema and config
|
|
bd info --schema --json
|
|
|
|
# Preview migration changes
|
|
bd migrate --dry-run
|
|
|
|
# Migrate old databases to beads.db
|
|
bd migrate
|
|
|
|
# Migrate and clean up old files
|
|
bd migrate --cleanup --yes
|
|
```
|
|
|
|
**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
|
|
|
|
## Database maintenance
|
|
|
|
As your project accumulates closed issues, the database grows. Manage size with these commands:
|
|
|
|
```bash
|
|
# View compaction statistics
|
|
bd admin compact --stats
|
|
|
|
# Preview compaction candidates (30+ days closed)
|
|
bd admin compact --analyze --json
|
|
|
|
# Apply agent-generated summary
|
|
bd admin compact --apply --id bd-42 --summary summary.txt
|
|
|
|
# Immediately delete closed issues (CAUTION: permanent!)
|
|
bd admin cleanup --force
|
|
```
|
|
|
|
**When to compact:**
|
|
- Database file > 10MB with many old closed issues
|
|
- After major project milestones when old issues are no longer relevant
|
|
- Before archiving a project phase
|
|
|
|
**Note:** Compaction is permanent graceful decay. Original content is discarded but viewable via `bd restore <id>` from git history.
|
|
|
|
## Next steps
|
|
|
|
- Add labels: `bd create "Task" -l "backend,urgent"`
|
|
- Filter ready work: `bd ready --priority 1`
|
|
- Explain the graph: `bd ready --explain`
|
|
- Check graph integrity: `bd graph check`
|
|
- Search issues: `bd list --status open`
|
|
- Detect cycles: `bd dep cycles`
|
|
- Gates for PR/CI sync: [`bd gate`](/cli-reference/gate)
|
|
- More sync scenarios: [`bd dolt`](/cli-reference/dolt)
|
|
- Full command list: [CLI Reference](/cli-reference)
|
|
|
|
See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.
|