# Check database path and server status
bd info --json

# Example output:
# {
#   "database_path": "/path/to/.beads/beads.db",
#   "issue_prefix": "bd",
#   "agent_mail_enabled": false
# }

# Find ready work (no blockers, not already claimed)
bd ready --json

# Atomically claim an issue from the ready queue
bd update <id> --claim --json               # Fails if already claimed

# Find stale issues (not updated recently)
bd stale --days 30 --json                    # Default: 30 days
bd stale --days 90 --status in_progress --json  # Find abandoned claims
bd stale --limit 20 --json                   # Limit results

# Basic creation
# IMPORTANT: Always quote titles and descriptions with double quotes
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json

# Create with explicit ID (for parallel workers)
bd create "Issue title" --id worker1-100 -p 1 --json

# Create with labels (--labels or --label work)
bd create "Issue title" -t bug -p 1 -l bug,critical --json
bd create "Issue title" -t bug -p 1 --label bug,critical --json

# Examples with special characters (all require quoting):
bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json
bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json
bd create "Implement auth" --spec-id "docs/specs/auth.md" --json

# Create multiple issues from markdown file
bd create -f feature-plan.md --json

# Create with description from file (avoids shell escaping issues)
bd create "Issue title" --body-file=description.md --json
bd create "Issue title" --body-file description.md -p 1 --json

# Read description from stdin
echo "Description text" | bd create "Issue title" --stdin --json
cat description.md | bd create "Issue title" --stdin -p 1 --json
# --body-file=- also works:
echo "Description text" | bd create "Issue title" --body-file=- --json

# Create epic with hierarchical child tasks
bd create "Auth System" -t epic -p 1 --json                     # Returns: bd-a3f8e9
bd create "Login UI" -p 1 --parent bd-a3f8e9 --json             # Auto-assigned: bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 --json   # Auto-assigned: bd-a3f8e9.2
bd create "Tests" -p 1 --parent bd-a3f8e9 --json                # Auto-assigned: bd-a3f8e9.3

# Create and link discovered work (one command)
bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json

# Create with external reference (v0.9.2+)
bd create "Fix login" -t bug -p 1 --external-ref "gh-123" --json  # Short form
bd create "Fix login" -t bug -p 1 --external-ref "https://github.com/org/repo/issues/123" --json  # Full URL
bd create "Jira task" -t task -p 1 --external-ref "jira-PROJ-456" --json  # Custom prefix

# Update one or more issues
bd update <id> [<id>...] --claim --json
bd update <id> [<id>...] --priority 1 --json
bd update <id> [<id>...] --spec-id "docs/specs/auth.md" --json

# Update external reference (v0.9.2+)
bd update <id> --external-ref "gh-456" --json           # Short form
bd update <id> --external-ref "jira-PROJ-789" --json    # Custom prefix

# Atomically claim an issue for work (prevents race conditions)
# Sets assignee to you and status to in_progress in one atomic operation
# Fails if already claimed (assignee is not empty)
bd update <id> --claim --json

# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents)
# NOTE: This command is intentionally NOT exposed via the MCP server
# Agents should use 'bd update' with field-specific parameters instead
bd edit <id>                    # Edit description
bd edit <id> --title            # Edit title
bd edit <id> --design           # Edit design notes
bd edit <id> --notes            # Edit notes
bd edit <id> --acceptance       # Edit acceptance criteria

# Complete work (supports multiple IDs)
bd close <id> [<id>...] --reason "Done" --json

# Reopen closed issues (supports multiple IDs)
bd reopen <id> [<id>...] --reason "Reopening" --json

# Show dependency tree
bd dep tree <id>

# Get issue details (supports multiple IDs)
bd show <id> [<id>...] --json

# Show the currently active issue (in-progress, hooked, or last touched)
bd show --current

# Link discovered work (old way - two commands)
bd dep add <discovered-id> <parent-id> --type discovered-from

# Create and link in one command (new way - preferred)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json

# Label management (supports multiple IDs)
bd label add <id> [<id>...] <label> --json
bd label remove <id> [<id>...] <label> --json
bd label list <id> --json
bd label list-all --json

# Query current state value
bd state <id> <dimension>                    # Output: value
bd state agent-abc patrol                  # Output: active
bd state --json agent-abc patrol           # {"issue_id": "...", "dimension": "patrol", "value": "active"}

# List all state dimensions on an issue
bd state list <id> --json
bd state list agent-abc                    # patrol: active, mode: normal, health: healthy

# Set state (creates event + updates label atomically)
bd set-state <id> <dimension>=<value> --reason "explanation" --json
bd set-state agent-abc patrol=muted --reason "Investigating stuck worker"
bd set-state agent-abc mode=degraded --reason "High error rate"

# Filter by status, priority, type
bd list --status open --priority 1 --json               # Status and priority
bd list --assignee alice --json                         # By assignee
bd list --type bug --json                               # By issue type
bd list --id bd-123,bd-456 --json                       # Specific IDs
bd list --spec "docs/specs/" --json                     # Spec prefix

# Labels (AND: must have ALL)
bd list --label bug,critical --json

# Labels (OR: has ANY)
bd list --label-any frontend,backend --json

# Title search (substring)
bd list --title "auth" --json

# Pattern matching (case-insensitive substring)
bd list --title-contains "auth" --json                  # Search in title
bd list --desc-contains "implement" --json              # Search in description
bd list --notes-contains "TODO" --json                  # Search in notes

# Find beads issue by external reference
bd list --json | jq -r '.[] | select(.external_ref == "gh-123") | .id'

# Date range filters (YYYY-MM-DD or RFC3339)
bd list --created-after 2024-01-01 --json               # Created after date
bd list --created-before 2024-12-31 --json              # Created before date
bd list --updated-after 2024-06-01 --json               # Updated after date
bd list --updated-before 2024-12-31 --json              # Updated before date
bd list --closed-after 2024-01-01 --json                # Closed after date
bd list --closed-before 2024-12-31 --json               # Closed before date

# Empty/null checks
bd list --empty-description --json                      # Issues with no description
bd list --no-assignee --json                            # Unassigned issues
bd list --no-labels --json                              # Issues with no labels

# Priority ranges
bd list --priority-min 0 --priority-max 1 --json        # P0 and P1 only
bd list --priority-min 2 --json                         # P2 and below

# Combine multiple filters
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json

# Explicitly enable sandbox mode
bd --sandbox <command>

# JSON output for programmatic use
bd --json <command>

# Disable auto-sync
bd --no-auto-flush <command>    # Disable auto-flush
bd --no-auto-import <command>   # Disable auto-import

# Custom database path
bd --db /path/to/.beads/beads.db <command>

# Custom actor for audit trail
bd --actor alice <command>

# Clean up closed issues (bulk deletion)
bd admin cleanup --force --json                                   # Delete ALL closed issues
bd admin cleanup --older-than 30 --force --json                   # Delete closed >30 days ago
bd admin cleanup --dry-run --json                                 # Preview what would be deleted
bd admin cleanup --older-than 90 --cascade --force --json         # Delete old + dependents

# Basic usage - scan current repo
bd orphans

# Cross-repo: scan CODE repo's commits against external BEADS database
cd ~/my-code-repo
bd orphans --db ~/my-beads-repo/.beads/beads.db

# JSON output
bd orphans --json

# Find and merge duplicate issues
bd duplicates                                          # Show all duplicates
bd duplicates --auto-merge                             # Automatically merge all
bd duplicates --dry-run                                # Preview merge operations

# Merge specific duplicate issues
bd merge <source-id...> --into <target-id> --json      # Consolidate duplicates
bd merge bd-42 bd-43 --into bd-41 --dry-run            # Preview merge

# Agent-driven compaction
bd admin compact --analyze --json                           # Get candidates for review
bd admin compact --analyze --tier 1 --limit 10 --json       # Limited batch
bd admin compact --apply --id bd-42 --summary summary.txt   # Apply compaction
bd admin compact --apply --id bd-42 --summary - < summary.txt  # From stdin
bd admin compact --stats --json                             # Show statistics

# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
bd admin compact --auto --dry-run --all                     # Preview
bd admin compact --auto --all --tier 1                      # Auto-compact tier 1

# Restore compacted issue from git history
bd restore <id>  # View full history at time of compaction

# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
bd rename-prefix kw- --dry-run  # Preview changes
bd rename-prefix kw- --json     # Apply rename

# Preview what would be removed (dry-run)
bd admin reset

# Actually perform the reset
bd admin reset --force

# List available formulas (templates)
bd formula list --json

# Show proto structure and variables
bd mol show <proto-id> --json

# Extract proto from ad-hoc epic
bd mol distill <epic-id> --json

# Instantiate proto as persistent mol (solid → liquid)
bd mol pour <proto-id> --var key=value --json

# Preview what would be created
bd mol pour <proto-id> --var key=value --dry-run

# Assign root issue
bd mol pour <proto-id> --var key=value --assignee alice --json

# Attach additional protos during pour
bd mol pour <proto-id> --attach <other-proto> --json

# Instantiate proto as ephemeral wisp (solid → vapor)
bd mol wisp <proto-id> --var key=value --json

# List all wisps
bd mol wisp list --json
bd mol wisp list --all --json    # Include closed

# Garbage collect orphaned wisps
bd mol wisp gc --json
bd mol wisp gc --age 24h --json  # Custom age threshold
bd mol wisp gc --dry-run         # Preview what would be cleaned

# Purge all closed wisps (bulk cleanup)
bd mol wisp gc --closed              # Preview closed wisp deletion
bd mol wisp gc --closed --force      # Delete all closed wisps
bd mol wisp gc --closed --dry-run    # Detailed dry-run preview

# Polymorphic combine - handles proto+proto, proto+mol, mol+mol
bd mol bond <A> <B> --json

# Bond types
bd mol bond <A> <B> --type sequential --json   # B runs after A (default)
bd mol bond <A> <B> --type parallel --json     # B runs alongside A
bd mol bond <A> <B> --type conditional --json  # B runs only if A fails

# Phase control
bd mol bond <proto> <mol> --pour --json   # Force persistent spawn
bd mol bond <proto> <mol> --wisp --json   # Force ephemeral spawn

# Dynamic bonding (custom child IDs)
bd mol bond <proto> <mol> --ref arm-{{name}} --var name=ace --json

# Preview bonding
bd mol bond <A> <B> --dry-run

# Compress wisp to permanent digest
bd mol squash <ephemeral-id> --json

# With agent-provided summary
bd mol squash <ephemeral-id> --summary "Work completed" --json

# Preview
bd mol squash <ephemeral-id> --dry-run

# Keep wisp children after squash
bd mol squash <ephemeral-id> --keep-children --json

# Delete wisp without digest (destructive)
bd mol burn <ephemeral-id> --json

# Preview
bd mol burn <ephemeral-id> --dry-run

# Skip confirmation
bd mol burn <ephemeral-id> --force --json

# List open gates
bd gate list
bd gate list --all                       # Including closed

# Show gate details
bd gate show <gate-id>

# Evaluate gates and close resolved ones
bd gate check                            # All gates
bd gate check --type=gh:pr               # Only PR merge gates
bd gate check --type=gh:run              # Only CI run gates
bd gate check --type=timer               # Only timer gates
bd gate check --type=bead               # Only cross-rig bead gates
bd gate check --dry-run                  # Preview without changes
bd gate check --escalate                 # Escalate failed gates

# Manually resolve a gate
bd gate resolve <gate-id> --reason "Approved"

# Auto-discover CI run IDs for gh:run gates
bd gate discover
bd gate discover --dry-run --branch main

# Add a waiter to a gate
bd gate add-waiter <gate-id> <waiter>

# Export issues to issue JSONL
bd export -o issues.jsonl

# Dolt-native backup (preserves full commit history)
bd backup init /path/to/backup    # Register a backup destination
bd backup sync                   # Push to backup destination
bd backup restore [path]         # Restore from a backup
bd backup remove                 # Remove backup destination
bd backup status                 # Show backup status

# Bootstrap a new database from an issue export
bd init --from-jsonl                            # Reads .beads/issues.jsonl

# Configure orphan handling for pulls and bootstrapping
bd config set import.orphan_handling "resurrect"
bd dolt pull  # Respects import.orphan_handling setting

# Migrate databases after version upgrade
bd migrate                                             # Detect and migrate old databases
bd migrate --dry-run                                   # Preview migration
bd migrate --cleanup --yes                             # Migrate and remove old files

# AI-supervised migration (check before running bd migrate)
bd migrate --inspect --json                            # Show migration plan for AI agents
bd info --schema --json                                # Get schema, tables, config, sample IDs

# Basic setup (creates orphan branch by default)
bd migrate sync beads-sync                             # Create orphan sync branch
bd migrate sync beads-sync --dry-run                   # Preview without changes

# Force reconfigure if already set up
bd migrate sync beads-sync --force                     # Reconfigure sync branch

# Migrate existing non-orphan branch to orphan
bd migrate sync beads-sync --orphan                    # Delete and recreate as orphan

# Manual sync (push changes to remote)
bd dolt push

# Pull changes from remote
bd dolt pull

# What these do:
# bd dolt push - Commit pending changes to Dolt and push to remote
# bd dolt pull - Pull from remote and merge any updates

# Set a value
bd kv set <key> <value>
bd kv set feature_flag true
bd kv set api_endpoint https://api.example.com

# Get a value
bd kv get <key>
bd kv get feature_flag                 # Prints: true
bd kv get missing_key                  # Prints: missing_key (not set), exits 1

# Delete a key
bd kv clear <key>
bd kv clear feature_flag

# List all key-value pairs
bd kv list
bd kv list --json                      # Machine-readable output

# Simple format (backward compatible — statuses get no category)
bd config set status.custom "in_review,qa_testing,on_hold"

# Category-annotated format
bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen"

# Mixed format (some with categories, some without)
bd config set status.custom "in_review:active,legacy_status,archived:done"

bd statuses          # Human-readable table
bd statuses --json   # JSON output for programmatic use

# Single issue
bd show bd-42 --json

# List of issues
bd ready --json

# Operation result
bd create "Issue" -p 1 --json

bd ready
# ○ bd-42 [P1] [bug] - Fix authentication bug
# ○ bd-43 [P2] [feature] - Add user settings page

bd list --parent epic-123
# ○ bd-123.1 [P1] [task] - Design API (blocks: bd-123.2, bd-123.3)
# ○ bd-123.2 [P1] [task] - Implement endpoints (blocked by: bd-123.1, blocks: bd-123.3)
# ○ bd-123.3 [P1] [task] - Add tests (blocked by: bd-123.1, bd-123.2)

# 1. Find available work
bd ready --json

# 2. Claim issue
bd update bd-42 --claim --json

# 3. Work on it...

# 4. Close when done
bd close bd-42 --reason "Implemented and tested" --json

# While working on bd-100, discover a bug

# Old way (two commands):
bd create "Found auth bug" -t bug -p 1 --json  # Returns bd-101
bd dep add bd-101 bd-100 --type discovered-from

# New way (one command):
bd create "Found auth bug" -t bug -p 1 --deps discovered-from:bd-100 --json

# Update multiple issues at once
bd update bd-41 bd-42 bd-43 --priority 0 --json

# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json

# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json

# Start of session
bd ready --json  # Find work

# During session
bd create "..." -p 1 --json
bd update bd-42 --claim --json
# ... work ...

# End of session (IMPORTANT!)
bd dolt push  # Force immediate sync, bypass debounce

# Setup editor integration (choose based on your editor)
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md (universal standard)
bd setup codex    # Codex CLI - creates/updates AGENTS.md
bd setup mux      # Mux - creates/updates AGENTS.md
bd setup claude   # Claude Code - installs hooks + manages CLAUDE.md (minimal profile)
bd setup gemini   # Gemini CLI - installs hooks + manages GEMINI.md (minimal profile)
bd setup cursor   # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider    # Aider - creates .aider.conf.yml

# Check if integration is installed
bd setup factory --check
bd setup codex --check
bd setup mux --check
bd setup claude --check
bd setup gemini --check
bd setup cursor --check
bd setup aider --check

# Remove integration
bd setup factory --remove
bd setup codex --remove
bd setup mux --remove
bd setup claude --remove
bd setup gemini --remove
bd setup cursor --remove
bd setup aider --remove

bd setup claude              # Install globally (~/.claude/settings.json)
bd setup claude --project    # Install for this project only
bd setup claude --stealth    # Use stealth mode (flush only, no git operations)
bd setup gemini              # Install globally (~/.gemini/settings.json)
bd setup gemini --project    # Install for this project only
bd setup gemini --stealth    # Use stealth mode (flush only, no git operations)
bd setup mux --project       # Also install .mux/AGENTS.md workspace layer
bd setup mux --global        # Also install ~/.mux/AGENTS.md global layer