7f93a602d2
- Provides comprehensive workflow patterns and decision criteria - Includes quick reference (SKILL.md) and detailed references - Teaches when to use bd vs markdown/TodoWrite - Covers dependency types and issue lifecycle management - Complements existing plugin with usage philosophy
366 lines
8.0 KiB
Markdown
366 lines
8.0 KiB
Markdown
# CLI Reference
|
|
|
|
Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output.
|
|
|
|
## Contents
|
|
|
|
- [Quick Reference](#quick-reference)
|
|
- [Global Flags](#global-flags)
|
|
- [Core Commands](#core-commands)
|
|
- [bd ready](#bd-ready) - Find unblocked work
|
|
- [bd create](#bd-create) - Create new issues
|
|
- [bd update](#bd-update) - Update issue status, priority, assignee
|
|
- [bd close](#bd-close) - Close completed work
|
|
- [bd show](#bd-show) - Show issue details
|
|
- [bd list](#bd-list) - List issues with filters
|
|
- [Dependency Commands](#dependency-commands)
|
|
- [bd dep add](#bd-dep-add) - Create dependencies
|
|
- [bd dep tree](#bd-dep-tree) - Visualize dependency trees
|
|
- [bd dep cycles](#bd-dep-cycles) - Detect circular dependencies
|
|
- [Monitoring Commands](#monitoring-commands)
|
|
- [bd stats](#bd-stats) - Project statistics
|
|
- [bd blocked](#bd-blocked) - Find blocked work
|
|
- [Setup Commands](#setup-commands)
|
|
- [bd init](#bd-init) - Initialize database
|
|
- [bd quickstart](#bd-quickstart) - Show quick start guide
|
|
- [Common Workflows](#common-workflows)
|
|
- [JSON Output](#json-output)
|
|
- [Database Auto-Discovery](#database-auto-discovery)
|
|
- [Git Integration](#git-integration)
|
|
- [Tips](#tips)
|
|
|
|
## Quick Reference
|
|
|
|
| Command | Purpose | Key Flags |
|
|
|---------|---------|-----------|
|
|
| `bd ready` | Find unblocked work | `--priority`, `--assignee`, `--limit`, `--json` |
|
|
| `bd list` | List all issues with filters | `--status`, `--priority`, `--type`, `--assignee` |
|
|
| `bd show` | Show issue details | `--json` |
|
|
| `bd create` | Create new issue | `-t`, `-p`, `-d`, `--design`, `--acceptance` |
|
|
| `bd update` | Update existing issue | `--status`, `--priority`, `--design` |
|
|
| `bd close` | Close completed issue | `--reason` |
|
|
| `bd dep add` | Add dependency | `--type` (blocks, related, parent-child, discovered-from) |
|
|
| `bd dep tree` | Visualize dependency tree | (no flags) |
|
|
| `bd dep cycles` | Detect circular dependencies | (no flags) |
|
|
| `bd stats` | Get project statistics | `--json` |
|
|
| `bd blocked` | Find blocked issues | `--json` |
|
|
| `bd init` | Initialize bd in directory | `--prefix` |
|
|
| `bd quickstart` | Show quick start guide | (no flags) |
|
|
|
|
## Global Flags
|
|
|
|
Available for all commands:
|
|
|
|
```bash
|
|
--json # Output in JSON format
|
|
--db /path/to/db # Specify database path (default: auto-discover)
|
|
--actor "name" # Actor name for audit trail
|
|
--no-auto-flush # Disable automatic JSONL sync
|
|
--no-auto-import # Disable automatic JSONL import
|
|
```
|
|
|
|
## Core Commands
|
|
|
|
### bd ready
|
|
|
|
Find tasks with no blockers - ready to be worked on.
|
|
|
|
```bash
|
|
bd ready # All ready work
|
|
bd ready --json # JSON format
|
|
bd ready --priority 0 # Only priority 0 (critical)
|
|
bd ready --assignee alice # Only assigned to alice
|
|
bd ready --limit 5 # Limit to 5 results
|
|
```
|
|
|
|
**Use at session start** to see available work.
|
|
|
|
---
|
|
|
|
### bd create
|
|
|
|
Create a new issue with optional metadata.
|
|
|
|
```bash
|
|
bd create "Title"
|
|
bd create "Title" -t bug -p 0
|
|
bd create "Title" -d "Description"
|
|
bd create "Title" --design "Design notes"
|
|
bd create "Title" --acceptance "Definition of done"
|
|
bd create "Title" --assignee alice
|
|
```
|
|
|
|
**Flags**:
|
|
- `-t, --type`: task (default), bug, feature, epic, chore
|
|
- `-p, --priority`: 0-3 (default: 2)
|
|
- `-d, --description`: Issue description
|
|
- `--design`: Design notes
|
|
- `--acceptance`: Acceptance criteria
|
|
- `--assignee`: Who should work on this
|
|
|
|
---
|
|
|
|
### bd update
|
|
|
|
Update an existing issue's metadata.
|
|
|
|
```bash
|
|
bd update issue-123 --status in_progress
|
|
bd update issue-123 --priority 0
|
|
bd update issue-123 --design "Decided to use Redis"
|
|
bd update issue-123 --acceptance "Tests passing"
|
|
```
|
|
|
|
**Status values**: open, in_progress, blocked, closed
|
|
|
|
---
|
|
|
|
### bd close
|
|
|
|
Close (complete) an issue.
|
|
|
|
```bash
|
|
bd close issue-123
|
|
bd close issue-123 --reason "Implemented in PR #42"
|
|
bd close issue-1 issue-2 issue-3 --reason "Bulk close"
|
|
```
|
|
|
|
**Note**: Closed issues remain in database for history.
|
|
|
|
---
|
|
|
|
### bd show
|
|
|
|
Show detailed information about a specific issue.
|
|
|
|
```bash
|
|
bd show issue-123
|
|
bd show issue-123 --json
|
|
```
|
|
|
|
Shows: all fields, dependencies, dependents, audit history.
|
|
|
|
---
|
|
|
|
### bd list
|
|
|
|
List all issues with optional filters.
|
|
|
|
```bash
|
|
bd list # All issues
|
|
bd list --status open # Only open
|
|
bd list --priority 0 # Critical
|
|
bd list --type bug # Only bugs
|
|
bd list --assignee alice # By assignee
|
|
bd list --status closed --limit 10 # Recent completions
|
|
```
|
|
|
|
---
|
|
|
|
## Dependency Commands
|
|
|
|
### bd dep add
|
|
|
|
Add a dependency between issues.
|
|
|
|
```bash
|
|
bd dep add from-issue to-issue # blocks (default)
|
|
bd dep add from-issue to-issue --type blocks
|
|
bd dep add from-issue to-issue --type related
|
|
bd dep add epic-id task-id --type parent-child
|
|
bd dep add original-id found-id --type discovered-from
|
|
```
|
|
|
|
**Dependency types**:
|
|
1. **blocks**: from-issue blocks to-issue (hard blocker)
|
|
2. **related**: Soft link (no blocking)
|
|
3. **parent-child**: Epic/subtask hierarchy
|
|
4. **discovered-from**: Tracks origin of discovery
|
|
|
|
---
|
|
|
|
### bd dep tree
|
|
|
|
Visualize full dependency tree for an issue.
|
|
|
|
```bash
|
|
bd dep tree issue-123
|
|
```
|
|
|
|
Shows all dependencies and dependents in tree format.
|
|
|
|
---
|
|
|
|
### bd dep cycles
|
|
|
|
Detect circular dependencies.
|
|
|
|
```bash
|
|
bd dep cycles
|
|
```
|
|
|
|
Finds dependency cycles that would prevent work from being ready.
|
|
|
|
---
|
|
|
|
## Monitoring Commands
|
|
|
|
### bd stats
|
|
|
|
Get project statistics.
|
|
|
|
```bash
|
|
bd stats
|
|
bd stats --json
|
|
```
|
|
|
|
Returns: total, open, in_progress, closed, blocked, ready, avg lead time.
|
|
|
|
---
|
|
|
|
### bd blocked
|
|
|
|
Get blocked issues with blocker information.
|
|
|
|
```bash
|
|
bd blocked
|
|
bd blocked --json
|
|
```
|
|
|
|
Use to identify bottlenecks when ready list is empty.
|
|
|
|
---
|
|
|
|
## Setup Commands
|
|
|
|
### bd init
|
|
|
|
Initialize bd in current directory.
|
|
|
|
```bash
|
|
bd init # Auto-detect prefix
|
|
bd init --prefix api # Custom prefix
|
|
```
|
|
|
|
Creates `.beads/` directory and database.
|
|
|
|
---
|
|
|
|
### bd quickstart
|
|
|
|
Show comprehensive quick start guide.
|
|
|
|
```bash
|
|
bd quickstart
|
|
```
|
|
|
|
Displays built-in reference for command syntax and workflows.
|
|
|
|
---
|
|
|
|
## Common Workflows
|
|
|
|
### Session Start
|
|
|
|
```bash
|
|
bd ready --json
|
|
bd show issue-123
|
|
bd update issue-123 --status in_progress
|
|
```
|
|
|
|
### Discovery During Work
|
|
|
|
```bash
|
|
bd create "Found: bug in auth" -t bug
|
|
bd dep add current-issue new-issue --type discovered-from
|
|
```
|
|
|
|
### Completing Work
|
|
|
|
```bash
|
|
bd close issue-123 --reason "Implemented with tests passing"
|
|
bd ready # See what unblocked
|
|
```
|
|
|
|
### Planning Epic
|
|
|
|
```bash
|
|
bd create "OAuth Integration" -t epic
|
|
bd create "Set up credentials" -t task
|
|
bd create "Implement flow" -t task
|
|
|
|
bd dep add oauth-epic oauth-creds --type parent-child
|
|
bd dep add oauth-epic oauth-flow --type parent-child
|
|
bd dep add oauth-creds oauth-flow # creds blocks flow
|
|
|
|
bd dep tree oauth-epic
|
|
```
|
|
|
|
---
|
|
|
|
## JSON Output
|
|
|
|
All commands support `--json` for structured output:
|
|
|
|
```bash
|
|
bd ready --json
|
|
bd show issue-123 --json
|
|
bd list --status open --json
|
|
bd stats --json
|
|
```
|
|
|
|
Use when parsing programmatically or extracting specific fields.
|
|
|
|
---
|
|
|
|
## Database Auto-Discovery
|
|
|
|
bd finds database in this order:
|
|
|
|
1. `--db` flag: `bd ready --db /path/to/db.db`
|
|
2. `$BEADS_DB` environment variable
|
|
3. `.beads/*.db` in current directory or ancestors
|
|
4. `~/.beads/default.db` as fallback
|
|
|
|
**Project-local** (`.beads/`): Project-specific work, git-tracked
|
|
|
|
**Global fallback** (`~/.beads/`): Cross-project tracking, personal tasks
|
|
|
|
---
|
|
|
|
## Git Integration
|
|
|
|
bd automatically syncs with git:
|
|
|
|
- **After each operation**: Exports to JSONL (5s debounce)
|
|
- **After git pull**: Imports from JSONL if newer than DB
|
|
|
|
**Files**:
|
|
- `.beads/*.jsonl` - Source of truth (git-tracked)
|
|
- `.beads/*.db` - Local cache (gitignored)
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
**Use JSON for parsing**:
|
|
```bash
|
|
bd ready --json | jq '.[0].id'
|
|
```
|
|
|
|
**Bulk operations**:
|
|
```bash
|
|
bd close issue-1 issue-2 issue-3 --reason "Sprint complete"
|
|
```
|
|
|
|
**Quick filtering**:
|
|
```bash
|
|
bd list --status open --priority 0 --type bug
|
|
```
|
|
|
|
**Built-in help**:
|
|
```bash
|
|
bd quickstart # Comprehensive guide
|
|
bd create --help # Command-specific help
|
|
```
|