beads/website/docs/cli-reference/index.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

185 lines
3.7 KiB
Markdown

---
id: index
title: CLI Reference
sidebar_position: 1
---
# CLI Reference
Complete reference for all `bd` commands.
## Command Structure
```bash
bd [global-flags] <command> [command-flags] [arguments]
```
### Global Flags
| Flag | Description |
|------|-------------|
| `--db <path>` | Use specific database file |
| `--json` | Output in JSON format |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Verbose output |
| `--version` | Show version |
| `--help` | Show help |
## Command Categories
### Essential Commands
Most frequently used:
| Command | Description |
|---------|-------------|
| `bd create` | Create new issue |
| `bd list` | List issues with filters |
| `bd show` | Show issue details |
| `bd update` | Update issue fields |
| `bd close` | Close an issue |
| `bd ready` | Show unblocked work |
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
### Issue Management
| Command | Description |
|---------|-------------|
| `bd create` | Create issue |
| `bd show` | Show details |
| `bd update` | Update fields |
| `bd close` | Close issue |
| `bd delete` | Delete issue |
| `bd reopen` | Reopen closed issue |
### Dependencies
| Command | Description |
|---------|-------------|
| `bd dep add` | Add dependency |
| `bd dep remove` | Remove dependency |
| `bd dep tree` | Show dependency tree |
| `bd dep cycles` | Detect circular dependencies |
| `bd blocked` | Show blocked issues |
| `bd ready` | Show unblocked issues |
### Labels & Comments
| Command | Description |
|---------|-------------|
| `bd label add` | Add label to issue |
| `bd label remove` | Remove label |
| `bd label list` | List all labels |
| `bd comment add` | Add comment |
| `bd comment list` | List comments |
### Sync & Export
| Command | Description |
|---------|-------------|
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
| `bd export` | Export data to JSONL |
| `bd migrate` | Migrate database schema |
### System
| Command | Description |
|---------|-------------|
| `bd init` | Initialize beads in project |
| `bd info` | Show system info |
| `bd version` | Show version |
| `bd config` | Manage configuration |
| `bd doctor` | Check system health |
| `bd hooks` | Manage git hooks |
### Workflows
| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol` | Manage molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |
## Quick Reference
### Creating Issues
```bash
# Basic
bd create "Title" -t task -p 2
# With description
bd create "Title" --description="Details here" -t bug -p 1
# With labels
bd create "Title" -l "backend,urgent"
# As child of epic
bd create "Subtask" --parent bd-42
# With discovered-from link
bd create "Found bug" --deps discovered-from:bd-42
# JSON output
bd create "Title" --json
```
### Querying Issues
```bash
# All open issues
bd list --status open
# High priority bugs
bd list --status open --priority 0,1 --type bug
# With specific labels
bd list --label-any urgent,critical
# JSON output
bd list --json
```
### Working with Dependencies
```bash
# Add: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View tree
bd dep tree bd-2
# Find cycles
bd dep cycles
# What's ready to work?
bd ready
# What's blocked?
bd blocked
```
### Syncing
```bash
# Push changes to Dolt remote
bd dolt push
# Pull changes from Dolt remote
bd dolt pull
# Export to file
bd export -o backup.jsonl
```
## See Also
- [Essential Commands](/cli-reference/essential)
- [Issue Commands](/cli-reference/issues)
- [Dependency Commands](/cli-reference/dependencies)
- [Label Commands](/cli-reference/labels)
- [Sync Commands](/cli-reference/sync)