feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
Steve Yegge
240
website/docs/cli-reference/dependencies.md
Normal file
240
website/docs/cli-reference/dependencies.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
id: dependencies
|
||||
title: Dependency Commands
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Dependency Commands
|
||||
|
||||
Commands for managing issue dependencies.
|
||||
|
||||
## bd dep add
|
||||
|
||||
Add a dependency between issues.
|
||||
|
||||
```bash
|
||||
bd dep add <dependent> <dependency> [flags]
|
||||
```
|
||||
|
||||
**Semantics:** `<dependent>` depends on `<dependency>` (dependency blocks dependent).
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--type Dependency type (blocks|related|discovered-from)
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# bd-2 depends on bd-1 (bd-1 blocks bd-2)
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# Soft relationship
|
||||
bd dep add bd-2 bd-1 --type related
|
||||
|
||||
# JSON output
|
||||
bd dep add bd-2 bd-1 --json
|
||||
```
|
||||
|
||||
## bd dep remove
|
||||
|
||||
Remove a dependency.
|
||||
|
||||
```bash
|
||||
bd dep remove <dependent> <dependency> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd dep remove bd-2 bd-1
|
||||
bd dep remove bd-2 bd-1 --json
|
||||
```
|
||||
|
||||
## bd dep tree
|
||||
|
||||
Display dependency tree.
|
||||
|
||||
```bash
|
||||
bd dep tree <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--depth Maximum depth to display
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd dep tree bd-42
|
||||
bd dep tree bd-42 --depth 3
|
||||
bd dep tree bd-42 --json
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Dependency tree for bd-42:
|
||||
|
||||
> bd-42: Add authentication [P2] (open)
|
||||
> bd-41: Create API [P2] (open)
|
||||
> bd-40: Set up database [P1] (closed)
|
||||
```
|
||||
|
||||
## bd dep cycles
|
||||
|
||||
Detect circular dependencies.
|
||||
|
||||
```bash
|
||||
bd dep cycles [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd dep cycles
|
||||
bd dep cycles --json
|
||||
```
|
||||
|
||||
## bd ready
|
||||
|
||||
Show issues with no blockers.
|
||||
|
||||
```bash
|
||||
bd ready [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--priority Filter by priority
|
||||
--type Filter by type
|
||||
--label Filter by label
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd ready
|
||||
bd ready --priority 1
|
||||
bd ready --type bug
|
||||
bd ready --json
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Ready work (3 issues with no blockers):
|
||||
|
||||
1. [P1] bd-40: Set up database
|
||||
2. [P2] bd-45: Write tests
|
||||
3. [P3] bd-46: Update docs
|
||||
```
|
||||
|
||||
## bd blocked
|
||||
|
||||
Show blocked issues and their blockers.
|
||||
|
||||
```bash
|
||||
bd blocked [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Blocked issues (2 issues):
|
||||
|
||||
bd-42: Add authentication
|
||||
Blocked by: bd-41 (open)
|
||||
|
||||
bd-41: Create API
|
||||
Blocked by: bd-40 (in_progress)
|
||||
```
|
||||
|
||||
## bd relate
|
||||
|
||||
Create a soft relationship between issues.
|
||||
|
||||
```bash
|
||||
bd relate <id1> <id2> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd relate bd-42 bd-43
|
||||
bd relate bd-42 bd-43 --json
|
||||
```
|
||||
|
||||
## bd duplicate
|
||||
|
||||
Mark an issue as duplicate.
|
||||
|
||||
```bash
|
||||
bd duplicate <id> --of <canonical> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd duplicate bd-43 --of bd-42
|
||||
bd duplicate bd-43 --of bd-42 --json
|
||||
```
|
||||
|
||||
## bd supersede
|
||||
|
||||
Mark an issue as superseding another.
|
||||
|
||||
```bash
|
||||
bd supersede <old> --with <new> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd supersede bd-42 --with bd-50
|
||||
bd supersede bd-42 --with bd-50 --json
|
||||
```
|
||||
|
||||
## Understanding Dependencies
|
||||
|
||||
### Blocking vs Non-blocking
|
||||
|
||||
| Type | Blocks Ready Queue | Use Case |
|
||||
|------|-------------------|----------|
|
||||
| `blocks` | Yes | Hard dependency |
|
||||
| `parent-child` | No | Epic/subtask hierarchy |
|
||||
| `discovered-from` | No | Track origin |
|
||||
| `related` | No | Soft link |
|
||||
| `duplicates` | No | Mark duplicate |
|
||||
| `supersedes` | No | Version chain |
|
||||
|
||||
### Dependency Direction
|
||||
|
||||
```bash
|
||||
# bd-2 depends on bd-1
|
||||
# Meaning: bd-1 must complete before bd-2 can start
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# After bd-1 closes:
|
||||
bd close bd-1
|
||||
bd ready # bd-2 now appears
|
||||
```
|
||||
|
||||
### Avoiding Cycles
|
||||
|
||||
```bash
|
||||
# Check before adding complex dependencies
|
||||
bd dep cycles
|
||||
|
||||
# If cycle detected, remove one dependency
|
||||
bd dep remove bd-A bd-B
|
||||
```
|
||||
215
website/docs/cli-reference/essential.md
Normal file
215
website/docs/cli-reference/essential.md
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
id: essential
|
||||
title: Essential Commands
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Essential Commands
|
||||
|
||||
The most important commands for daily use.
|
||||
|
||||
## bd create
|
||||
|
||||
Create a new issue.
|
||||
|
||||
```bash
|
||||
bd create <title> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Short | Description |
|
||||
|------|-------|-------------|
|
||||
| `--type` | `-t` | Issue type: bug, feature, task, epic, chore |
|
||||
| `--priority` | `-p` | Priority: 0-4 (0=critical, 4=backlog) |
|
||||
| `--description` | `-d` | Detailed description |
|
||||
| `--labels` | `-l` | Comma-separated labels |
|
||||
| `--parent` | | Parent issue ID (for hierarchical) |
|
||||
| `--deps` | | Dependencies (e.g., `discovered-from:bd-42`) |
|
||||
| `--json` | | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd create "Fix login bug" -t bug -p 1
|
||||
bd create "Add dark mode" -t feature -p 2 --description="User requested"
|
||||
bd create "Subtask" --parent bd-42 -p 2
|
||||
bd create "Found during work" --deps discovered-from:bd-42 --json
|
||||
```
|
||||
|
||||
## bd list
|
||||
|
||||
List issues with filters.
|
||||
|
||||
```bash
|
||||
bd list [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--status` | Filter by status: open, in_progress, closed |
|
||||
| `--priority` | Filter by priority (comma-separated) |
|
||||
| `--type` | Filter by type (comma-separated) |
|
||||
| `--label-any` | Issues with any of these labels |
|
||||
| `--label-all` | Issues with all of these labels |
|
||||
| `--json` | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd list --status open
|
||||
bd list --priority 0,1 --type bug
|
||||
bd list --label-any urgent,critical --json
|
||||
```
|
||||
|
||||
## bd show
|
||||
|
||||
Show issue details.
|
||||
|
||||
```bash
|
||||
bd show <id> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd show bd-42
|
||||
bd show bd-42 --json
|
||||
bd show bd-42 bd-43 bd-44 # Multiple issues
|
||||
```
|
||||
|
||||
## bd update
|
||||
|
||||
Update issue fields.
|
||||
|
||||
```bash
|
||||
bd update <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--status` | New status |
|
||||
| `--priority` | New priority |
|
||||
| `--title` | New title |
|
||||
| `--description` | New description |
|
||||
| `--add-label` | Add label |
|
||||
| `--remove-label` | Remove label |
|
||||
| `--json` | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd update bd-42 --status in_progress
|
||||
bd update bd-42 --priority 0 --add-label urgent
|
||||
bd update bd-42 --title "Updated title" --json
|
||||
```
|
||||
|
||||
## bd close
|
||||
|
||||
Close an issue.
|
||||
|
||||
```bash
|
||||
bd close <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--reason` | Closure reason |
|
||||
| `--json` | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd close bd-42
|
||||
bd close bd-42 --reason "Fixed in PR #123"
|
||||
bd close bd-42 --json
|
||||
```
|
||||
|
||||
## bd ready
|
||||
|
||||
Show issues ready to work on (no blockers).
|
||||
|
||||
```bash
|
||||
bd ready [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--priority` | Filter by priority |
|
||||
| `--type` | Filter by type |
|
||||
| `--json` | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd ready
|
||||
bd ready --priority 1
|
||||
bd ready --json
|
||||
```
|
||||
|
||||
## bd blocked
|
||||
|
||||
Show blocked issues and their blockers.
|
||||
|
||||
```bash
|
||||
bd blocked [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
## bd sync
|
||||
|
||||
Force immediate sync to git.
|
||||
|
||||
```bash
|
||||
bd sync [flags]
|
||||
```
|
||||
|
||||
Performs:
|
||||
1. Export database to JSONL
|
||||
2. Git add `.beads/issues.jsonl`
|
||||
3. Git commit
|
||||
4. Git push
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd sync
|
||||
bd sync --json
|
||||
```
|
||||
|
||||
## bd info
|
||||
|
||||
Show system information.
|
||||
|
||||
```bash
|
||||
bd info [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--whats-new` | Show recent version changes |
|
||||
| `--schema` | Show database schema |
|
||||
| `--json` | JSON output |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd info
|
||||
bd info --whats-new
|
||||
bd info --json
|
||||
```
|
||||
|
||||
## bd stats
|
||||
|
||||
Show project statistics.
|
||||
|
||||
```bash
|
||||
bd stats [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd stats
|
||||
bd stats --json
|
||||
```
|
||||
185
website/docs/cli-reference/index.md
Normal file
185
website/docs/cli-reference/index.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
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 |
|
||||
| `--no-daemon` | Bypass daemon, direct database access |
|
||||
| `--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 sync` | Force sync to git |
|
||||
|
||||
### 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 sync` | Full sync cycle |
|
||||
| `bd export` | Export to JSONL |
|
||||
| `bd import` | Import from 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 daemons` | Manage daemons |
|
||||
| `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
|
||||
# Full sync (export + commit + push)
|
||||
bd sync
|
||||
|
||||
# Force export
|
||||
bd export
|
||||
|
||||
# Import from file
|
||||
bd import -i .beads/issues.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)
|
||||
230
website/docs/cli-reference/issues.md
Normal file
230
website/docs/cli-reference/issues.md
Normal file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
id: issues
|
||||
title: Issue Commands
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Issue Commands
|
||||
|
||||
Commands for managing issues.
|
||||
|
||||
## bd create
|
||||
|
||||
Create a new issue.
|
||||
|
||||
```bash
|
||||
bd create <title> [flags]
|
||||
```
|
||||
|
||||
**All flags:**
|
||||
```bash
|
||||
--type, -t Issue type (bug|feature|task|epic|chore)
|
||||
--priority, -p Priority 0-4
|
||||
--description, -d Detailed description
|
||||
--labels, -l Comma-separated labels
|
||||
--parent Parent issue ID
|
||||
--deps Dependencies (type:id format)
|
||||
--assignee Assigned user
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Bug with high priority
|
||||
bd create "Login fails with special chars" -t bug -p 1
|
||||
|
||||
# Feature with description
|
||||
bd create "Add export to PDF" -t feature -p 2 \
|
||||
--description="Users want to export reports as PDF files"
|
||||
|
||||
# Task with labels
|
||||
bd create "Update CI config" -t task -l "ci,infrastructure"
|
||||
|
||||
# Epic with children
|
||||
bd create "Auth System" -t epic -p 1
|
||||
bd create "Design login UI" --parent bd-42
|
||||
bd create "Implement backend" --parent bd-42
|
||||
|
||||
# Discovered issue
|
||||
bd create "Found SQL injection" -t bug -p 0 \
|
||||
--deps discovered-from:bd-42 --json
|
||||
```
|
||||
|
||||
## bd show
|
||||
|
||||
Display issue details.
|
||||
|
||||
```bash
|
||||
bd show <id>... [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--full Show all fields including comments
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd show bd-42
|
||||
bd show bd-42 --full
|
||||
bd show bd-42 bd-43 bd-44 --json
|
||||
```
|
||||
|
||||
## bd update
|
||||
|
||||
Update issue fields.
|
||||
|
||||
```bash
|
||||
bd update <id> [flags]
|
||||
```
|
||||
|
||||
**All flags:**
|
||||
```bash
|
||||
--status New status (open|in_progress|closed)
|
||||
--priority New priority (0-4)
|
||||
--title New title
|
||||
--description New description
|
||||
--type New type
|
||||
--add-label Add label(s)
|
||||
--remove-label Remove label(s)
|
||||
--assignee New assignee
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Start work
|
||||
bd update bd-42 --status in_progress
|
||||
|
||||
# Escalate priority
|
||||
bd update bd-42 --priority 0 --add-label urgent
|
||||
|
||||
# Change title and description
|
||||
bd update bd-42 --title "New title" --description="Updated description"
|
||||
|
||||
# Multiple changes
|
||||
bd update bd-42 --status in_progress --priority 1 --add-label "in-review" --json
|
||||
```
|
||||
|
||||
## bd close
|
||||
|
||||
Close an issue.
|
||||
|
||||
```bash
|
||||
bd close <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--reason Closure reason (stored in comment)
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd close bd-42
|
||||
bd close bd-42 --reason "Fixed in commit abc123"
|
||||
bd close bd-42 --reason "Duplicate of bd-43" --json
|
||||
```
|
||||
|
||||
## bd reopen
|
||||
|
||||
Reopen a closed issue.
|
||||
|
||||
```bash
|
||||
bd reopen <id> [flags]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd reopen bd-42
|
||||
bd reopen bd-42 --json
|
||||
```
|
||||
|
||||
## bd delete
|
||||
|
||||
Delete an issue.
|
||||
|
||||
```bash
|
||||
bd delete <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--force, -f Skip confirmation
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd delete bd-42
|
||||
bd delete bd-42 -f --json
|
||||
```
|
||||
|
||||
**Note:** Deletions are tracked in `.beads/deletions.jsonl` for sync.
|
||||
|
||||
## bd search
|
||||
|
||||
Search issues by text.
|
||||
|
||||
```bash
|
||||
bd search <query> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--status Filter by status
|
||||
--type Filter by type
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd search "authentication"
|
||||
bd search "login bug" --status open
|
||||
bd search "API" --type feature --json
|
||||
```
|
||||
|
||||
## bd duplicates
|
||||
|
||||
Find and manage duplicate issues.
|
||||
|
||||
```bash
|
||||
bd duplicates [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--auto-merge Automatically merge all duplicates
|
||||
--dry-run Preview without changes
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd duplicates
|
||||
bd duplicates --auto-merge
|
||||
bd duplicates --dry-run --json
|
||||
```
|
||||
|
||||
## bd merge
|
||||
|
||||
Merge duplicate issues.
|
||||
|
||||
```bash
|
||||
bd merge <source>... --into <target> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--into Target issue to merge into
|
||||
--dry-run Preview without changes
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd merge bd-42 bd-43 --into bd-41
|
||||
bd merge bd-42 bd-43 --into bd-41 --dry-run --json
|
||||
```
|
||||
125
website/docs/cli-reference/labels.md
Normal file
125
website/docs/cli-reference/labels.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
id: labels
|
||||
title: Labels & Comments
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Labels & Comments
|
||||
|
||||
Commands for managing labels and comments.
|
||||
|
||||
## Labels
|
||||
|
||||
### Adding Labels
|
||||
|
||||
```bash
|
||||
# During creation
|
||||
bd create "Task" -l "backend,urgent"
|
||||
|
||||
# To existing issue
|
||||
bd update bd-42 --add-label urgent
|
||||
bd update bd-42 --add-label "backend,security"
|
||||
```
|
||||
|
||||
### Removing Labels
|
||||
|
||||
```bash
|
||||
bd update bd-42 --remove-label urgent
|
||||
```
|
||||
|
||||
### Listing Labels
|
||||
|
||||
```bash
|
||||
# All labels in use
|
||||
bd label list
|
||||
bd label list --json
|
||||
|
||||
# Issues with specific labels
|
||||
bd list --label-any urgent,critical
|
||||
bd list --label-all backend,security
|
||||
```
|
||||
|
||||
### Label Conventions
|
||||
|
||||
Suggested label categories:
|
||||
|
||||
| Category | Examples | Purpose |
|
||||
|----------|----------|---------|
|
||||
| Type | `bug`, `feature`, `docs` | Issue classification |
|
||||
| Priority | `urgent`, `critical` | Urgency markers |
|
||||
| Area | `backend`, `frontend`, `api` | Code area |
|
||||
| Status | `blocked`, `needs-review` | Workflow state |
|
||||
| Size | `small`, `medium`, `large` | Effort estimate |
|
||||
|
||||
## Comments
|
||||
|
||||
### Adding Comments
|
||||
|
||||
```bash
|
||||
bd comment add bd-42 "Working on this now"
|
||||
bd comment add bd-42 --message "Found the bug in auth.go:45"
|
||||
```
|
||||
|
||||
### Listing Comments
|
||||
|
||||
```bash
|
||||
bd comment list bd-42
|
||||
bd comment list bd-42 --json
|
||||
```
|
||||
|
||||
### Viewing with Issue
|
||||
|
||||
```bash
|
||||
bd show bd-42 --full # Includes comments
|
||||
```
|
||||
|
||||
## Filtering by Labels
|
||||
|
||||
### Any Match (OR)
|
||||
|
||||
```bash
|
||||
# Issues with urgent OR critical
|
||||
bd list --label-any urgent,critical
|
||||
```
|
||||
|
||||
### All Match (AND)
|
||||
|
||||
```bash
|
||||
# Issues with BOTH backend AND security
|
||||
bd list --label-all backend,security
|
||||
```
|
||||
|
||||
### Combined Filters
|
||||
|
||||
```bash
|
||||
# Open bugs with urgent label
|
||||
bd list --status open --type bug --label-any urgent --json
|
||||
```
|
||||
|
||||
## Bulk Operations
|
||||
|
||||
### Add Label to Multiple Issues
|
||||
|
||||
```bash
|
||||
# Using shell
|
||||
for id in bd-42 bd-43 bd-44; do
|
||||
bd update $id --add-label "sprint-1"
|
||||
done
|
||||
```
|
||||
|
||||
### Find and Label
|
||||
|
||||
```bash
|
||||
# Label all open bugs as needs-triage
|
||||
bd list --status open --type bug --json | \
|
||||
jq -r '.[].id' | \
|
||||
xargs -I {} bd update {} --add-label needs-triage
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep labels lowercase** - `backend` not `Backend`
|
||||
2. **Use hyphens for multi-word** - `needs-review` not `needs_review`
|
||||
3. **Be consistent** - Establish team conventions
|
||||
4. **Don't over-label** - 2-4 labels per issue is typical
|
||||
5. **Review periodically** - Remove unused labels
|
||||
208
website/docs/cli-reference/sync.md
Normal file
208
website/docs/cli-reference/sync.md
Normal file
@@ -0,0 +1,208 @@
|
||||
---
|
||||
id: sync
|
||||
title: Sync & Export
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Sync & Export Commands
|
||||
|
||||
Commands for synchronizing with git.
|
||||
|
||||
## bd sync
|
||||
|
||||
Full sync cycle: export, commit, push.
|
||||
|
||||
```bash
|
||||
bd sync [flags]
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Exports database to `.beads/issues.jsonl`
|
||||
2. Stages the JSONL file
|
||||
3. Commits with auto-generated message
|
||||
4. Pushes to remote
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--json JSON output
|
||||
--dry-run Preview without changes
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd sync
|
||||
bd sync --json
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- End of work session
|
||||
- Before switching branches
|
||||
- After significant changes
|
||||
|
||||
## bd export
|
||||
|
||||
Export database to JSONL.
|
||||
|
||||
```bash
|
||||
bd export [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--output, -o Output file (default: .beads/issues.jsonl)
|
||||
--dry-run Preview without writing
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd export
|
||||
bd export -o backup.jsonl
|
||||
bd export --dry-run
|
||||
```
|
||||
|
||||
## bd import
|
||||
|
||||
Import from JSONL file.
|
||||
|
||||
```bash
|
||||
bd import -i <file> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--input, -i Input file (required)
|
||||
--dry-run Preview without changes
|
||||
--orphan-handling How to handle missing parents
|
||||
--dedupe-after Run duplicate detection after import
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Orphan handling modes:**
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `allow` | Import orphans without validation (default) |
|
||||
| `resurrect` | Restore deleted parents as tombstones |
|
||||
| `skip` | Skip orphaned children with warning |
|
||||
| `strict` | Fail if parent missing |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd import -i .beads/issues.jsonl
|
||||
bd import -i backup.jsonl --dry-run
|
||||
bd import -i issues.jsonl --orphan-handling resurrect
|
||||
bd import -i issues.jsonl --dedupe-after --json
|
||||
```
|
||||
|
||||
## bd migrate
|
||||
|
||||
Migrate database schema.
|
||||
|
||||
```bash
|
||||
bd migrate [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
```bash
|
||||
--inspect Show migration plan (for agents)
|
||||
--dry-run Preview without changes
|
||||
--cleanup Remove old files after migration
|
||||
--yes Skip confirmation
|
||||
--json JSON output
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd migrate --inspect --json
|
||||
bd migrate --dry-run
|
||||
bd migrate
|
||||
bd migrate --cleanup --yes
|
||||
```
|
||||
|
||||
## bd hooks
|
||||
|
||||
Manage git hooks.
|
||||
|
||||
```bash
|
||||
bd hooks <subcommand> [flags]
|
||||
```
|
||||
|
||||
**Subcommands:**
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `install` | Install git hooks |
|
||||
| `uninstall` | Remove git hooks |
|
||||
| `status` | Check hook status |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
bd hooks install
|
||||
bd hooks status
|
||||
bd hooks uninstall
|
||||
```
|
||||
|
||||
## Auto-Sync Behavior
|
||||
|
||||
### With Daemon (Default)
|
||||
|
||||
The daemon handles sync automatically:
|
||||
- Exports to JSONL after changes (5s debounce)
|
||||
- Imports from JSONL when newer
|
||||
|
||||
### Without Daemon
|
||||
|
||||
Use `--no-daemon` flag:
|
||||
- Changes only written to SQLite
|
||||
- Must manually export/sync
|
||||
|
||||
```bash
|
||||
bd --no-daemon create "Task"
|
||||
bd export # Manual export needed
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Merge Driver (Recommended)
|
||||
|
||||
Install the beads merge driver:
|
||||
|
||||
```bash
|
||||
bd init # Prompts for merge driver setup
|
||||
```
|
||||
|
||||
The driver automatically:
|
||||
- Merges non-conflicting changes
|
||||
- Preserves both sides for real conflicts
|
||||
- Uses latest timestamp for same-issue edits
|
||||
|
||||
### Manual Resolution
|
||||
|
||||
```bash
|
||||
# After merge conflict
|
||||
git checkout --ours .beads/issues.jsonl
|
||||
bd import -i .beads/issues.jsonl
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Deletion Tracking
|
||||
|
||||
Deletions sync via `.beads/deletions.jsonl`:
|
||||
|
||||
```bash
|
||||
# Delete issue
|
||||
bd delete bd-42
|
||||
|
||||
# View deletions
|
||||
bd deleted
|
||||
bd deleted --since=30d
|
||||
|
||||
# Deletions propagate via git
|
||||
git pull # Imports deletions from remote
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always sync at session end** - `bd sync`
|
||||
2. **Install git hooks** - `bd hooks install`
|
||||
3. **Use merge driver** - Avoids manual conflict resolution
|
||||
4. **Check sync status** - `bd info` shows daemon/sync state
|
||||
Reference in New Issue
Block a user