# 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
```