docs: sync skill CLI reference with current docs
Update examples/claude-code-skill/references/CLI_REFERENCE.md to match docs/CLI_REFERENCE.md. The skill version was ~17% smaller and missing newer sections like Global Flags, Sandbox Mode, Orphan Handling, etc. Fixes #401 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
@@ -1,4 +1,5 @@
|
||||
{"id":"bd-03r","title":"Document deletions manifest in AGENTS.md and README","description":"Parent: bd-imj\n\n## Task\nAdd documentation about the deletions manifest feature.\n\n## Locations to Update\n\n### AGENTS.md\n- Explain that deletions.jsonl is tracked in git\n- Document that `bd delete` records to the manifest\n- Explain cross-clone propagation mechanism\n\n### README.md \n- Brief mention in .beads directory structure section\n- Link to detailed docs if needed\n\n### docs/deletions.md (new file)\n- Full technical documentation\n- Format specification\n- Pruning policy\n- Git history fallback\n- Troubleshooting\n\n## Acceptance Criteria\n- AGENTS.md updated with deletion workflow\n- README.md mentions deletions.jsonl purpose\n- New docs/deletions.md with complete reference","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T14:56:49.13027-08:00","updated_at":"2025-11-25T15:17:23.145944-08:00","closed_at":"2025-11-25T15:17:23.145944-08:00"}
|
||||
{"id":"bd-0b2","title":"Need --no-git-history flag to disable git history backfill during import","description":"During JSONL migration (beads.jsonl → issues.jsonl), the git history backfill mechanism causes data loss by finding issues in the old beads.jsonl git history and incorrectly treating them as deleted.\n\nA --no-git-history flag for 'bd import' and 'bd sync' would allow users to disable the git history fallback when it's causing problems.\n\nUse cases:\n- JSONL filename migrations\n- Repos with complex git history\n- Debugging import issues\n- Performance (skip slow git scans)\n\nRelated: bd-0gh (migration causes spurious deletions)","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-26T22:28:22.5286-08:00","updated_at":"2025-11-26T23:14:22.957335-08:00","closed_at":"2025-11-26T23:14:22.957335-08:00"}
|
||||
{"id":"bd-1pj6","title":"Proposal: Custom status states via config","description":"Proposal to add 'custom status states' via `bd config`.\nUsers could define an optional issue status enum (e.g., awaiting_review, review_in_progress) in the config.\nThis would enable multi-step pipelines to process issues where each step correlates to a specific status.\n\nExamples:\n- awaiting_verification\n- awaiting_docs\n- awaiting_testing\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-20T18:55:48.670499-05:00","updated_at":"2025-11-20T18:55:48.670499-05:00"}
|
||||
{"id":"bd-2em","title":"Expand checkHooksQuick to verify all hook versions","description":"Currently checkHooksQuick only checks post-merge hook version. Should also check pre-commit, pre-push, and post-checkout for completeness. Keep it lightweight but catch more outdated hooks.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:47.432243-08:00","updated_at":"2025-11-25T19:50:21.378464-08:00","closed_at":"2025-11-25T19:50:21.378464-08:00"}
|
||||
{"id":"bd-39o","title":"Rename last_import_hash metadata key to jsonl_content_hash","description":"The metadata key 'last_import_hash' is misleading because it's updated on both import AND export (sync.go:614, import.go:320).\n\nBetter names:\n- jsonl_content_hash (more accurate)\n- last_sync_hash (clearer intent)\n\nThis is a breaking change requiring migration of existing metadata values.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:31:07.568739-05:00","updated_at":"2025-11-20T21:31:07.568739-05:00"}
|
||||
@@ -7,9 +8,13 @@
|
||||
{"id":"bd-4aao","title":"Fix failing integration tests in beads-mcp","description":"The `beads-mcp` test suite has failures in `tests/test_bd_client_integration.py` (assertion error in `test_init_creates_beads_directory`) and errors in `tests/test_worktree_separate_dbs.py` (setup failures finding database). These need to be investigated and fixed to ensure a reliable CI baseline.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-20T18:53:28.4803-05:00","updated_at":"2025-11-25T21:39:20.967106-08:00","closed_at":"2025-11-25T21:39:20.967106-08:00"}
|
||||
{"id":"bd-4h3","title":"Add test coverage for internal/git package","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:23.497486-05:00","updated_at":"2025-11-20T21:21:23.497486-05:00","dependencies":[{"issue_id":"bd-4h3","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.277639-05:00","created_by":"daemon"}]}
|
||||
{"id":"bd-4l5","title":"bd prime: Detect ephemeral branches and adjust workflow output","description":"When 'bd prime' runs on a branch with no upstream (ephemeral branch), it should output a different SESSION CLOSE PROTOCOL.\n\n**Current output (wrong for ephemeral branches):**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync\n[ ] 4. git commit -m \"...\"\n[ ] 5. bd sync\n[ ] 6. git push\n```\n\n**Needed output for ephemeral branches:**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync --from-main (pull updates from main)\n[ ] 4. git commit -m \"...\"\n[ ] 5. (no push - branch is ephemeral)\n```\n\n**Detection:** `git rev-parse --abbrev-ref --symbolic-full-name @{u}` returns error code 128 if no upstream.\n\nAlso update Sync \u0026 Collaboration section to mention `bd sync --from-main` for ephemeral branches.\n\n**Use case:** Gastown polecats work on ephemeral local branches that are never pushed. Their code gets merged to main via local merge, and beads changes stay local (communicated via gm mail to Overseer).","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-11-25T16:55:24.984104-08:00","updated_at":"2025-11-25T17:12:46.604978-08:00","closed_at":"2025-11-25T17:12:46.604978-08:00"}
|
||||
{"id":"bd-4pv","title":"bd export only outputs 1 issue after auto-import corrupts database","description":"When auto-import runs and purges issues (due to git history backfill bug), subsequent 'bd export' only exports 1 issue even though the database should have many.\n\nReproduction:\n1. Have issues.jsonl with 55 issues\n2. Auto-import triggers and purges all issues via git history backfill\n3. Run 'bd export' - only exports 1 issue (the last one created before corruption)\n\nThe database gets into an inconsistent state where most issues are purged but export doesn't realize this.\n\nWorkaround: Rebuild database from scratch with 'rm .beads/beads.db \u0026\u0026 bd init --prefix bd'","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:40.828866-08:00","updated_at":"2025-11-26T22:28:40.828866-08:00"}
|
||||
{"id":"bd-4t7","title":"Auto-import runs during --no-auto-import operations via stats/ready commands","description":"Even when using --no-auto-import flag, certain commands like 'bd stats' and 'bd ready' still trigger auto-import internally, which can cause the git history backfill bug to corrupt data.\n\nExample:\n bd stats --no-auto-import\n # Still prints 'Purged bd-xxx (recovered from git history...)'\n\nThe flag should completely disable auto-import for the command, but it appears some code paths still trigger it.\n\nWorkaround: Use --allow-stale instead, or --sandbox mode.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:59.305898-08:00","updated_at":"2025-11-26T22:28:59.305898-08:00"}
|
||||
{"id":"bd-736d","title":"Refactor path canonicalization into helper function","description":"The path canonicalization logic (filepath.Abs + EvalSymlinks) is duplicated in 3 places:\n- beads.go:131-137 (BEADS_DIR handling)\n- cmd/bd/main.go:446-451 (--no-db cleanup)\n- cmd/bd/nodb.go:26-31 (--no-db initialization)\n\nRefactoring suggestion:\nExtract to a helper function like:\n func canonicalizePath(path string) string\n\nThis would:\n- Reduce code duplication\n- Make the logic easier to maintain\n- Ensure consistent behavior across all path handling\n\nRelated to bd-e16b implementation.","status":"closed","priority":3,"issue_type":"chore","created_at":"2025-11-02T18:33:47.727443-08:00","updated_at":"2025-11-25T22:27:33.738672-08:00","closed_at":"2025-11-25T22:27:33.738672-08:00"}
|
||||
{"id":"bd-81a","title":"Add programmatic tip injection API","description":"Allow tips to be programmatically injected at runtime based on detected conditions. This enables dynamic tips (not just pre-defined ones) to be shown with custom priority and frequency.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-11T23:29:46.645583-08:00","updated_at":"2025-11-25T17:52:35.096882-08:00","closed_at":"2025-11-25T17:52:35.096882-08:00","dependencies":[{"issue_id":"bd-81a","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:46.646327-08:00","created_by":"daemon"}]}
|
||||
{"id":"bd-9e23","title":"Optimize Memory backend GetIssueByExternalRef with index","description":"Currently GetIssueByExternalRef in Memory storage uses O(n) linear search through all issues.\n\nCurrent code (memory.go:282-308):\nfor _, issue := range m.issues {\n if issue.ExternalRef != nil \u0026\u0026 *issue.ExternalRef == externalRef {\n return \u0026issueCopy, nil\n }\n}\n\nProposed optimization:\n- Add externalRefToID map[string]string to MemoryStorage\n- Maintain it in CreateIssue, UpdateIssue, DeleteIssue\n- Achieve O(1) lookup like SQLite's index\n\nImpact: Low (--no-db mode typically has smaller datasets)\nRelated: bd-1022","status":"open","priority":4,"issue_type":"chore","created_at":"2025-11-02T15:32:30.242357-08:00","updated_at":"2025-11-02T15:32:30.242357-08:00"}
|
||||
{"id":"bd-8a5","title":"Refactor: deduplicate FindJSONLInDir and FindJSONLPath","description":"## Background\n\nAfter fixing bd-tqo, we now have two nearly identical functions for finding the JSONL file:\n- `autoimport.FindJSONLInDir(dbDir string)` in internal/autoimport/autoimport.go\n- `beads.FindJSONLPath(dbPath string)` in internal/beads/beads.go\n\nBoth implement the same logic:\n1. Prefer issues.jsonl\n2. Fall back to beads.jsonl for legacy support\n3. Skip deletions.jsonl and merge artifacts\n4. Default to issues.jsonl if nothing found\n\n## Problem\n\nCode duplication means bug fixes need to be applied in multiple places (as we just experienced with bd-tqo).\n\n## Proposed Solution\n\nExtract shared logic to a utility package that both can import. Options:\n1. Create `internal/jsonlpath` package with the core logic\n2. Have `autoimport` import `beads` and call `FindJSONLPath` (but APIs differ slightly)\n3. Move to `internal/utils` if appropriate\n\nNeed to verify no import cycles would be created.\n\n## Affected Files\n- internal/autoimport/autoimport.go\n- internal/beads/beads.go","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-26T23:45:18.974339-08:00","updated_at":"2025-11-26T23:45:18.974339-08:00"}
|
||||
{"id":"bd-8an","title":"bd import auto-detects wrong prefix from directory name instead of issue IDs","description":"When importing issues.jsonl into a fresh database, 'bd import' prints:\n\n ✓ Initialized database with prefix 'beads' (detected from issues)\n\nBut the issues all have prefix 'bd-' (e.g., bd-03r). It appears to be detecting the prefix from the directory name (.beads/) rather than from the actual issue IDs in the JSONL.\n\nThis causes import to fail with:\n validate ID prefix for bd-03r: issue ID 'bd-03r' does not match configured prefix 'beads'\n\nWorkaround: Run 'bd config set issue_prefix bd' before import, or use 'bd init --prefix bd'.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:01.582564-08:00","updated_at":"2025-11-26T22:28:01.582564-08:00"}
|
||||
{"id":"bd-9e23","title":"Optimize Memory backend GetIssueByExternalRef with index","description":"Currently GetIssueByExternalRef in Memory storage uses O(n) linear search through all issues.\n\nCurrent code (memory.go:282-308):\nfor _, issue := range m.issues {\n if issue.ExternalRef != nil \u0026\u0026 *issue.ExternalRef == externalRef {\n return \u0026issueCopy, nil\n }\n}\n\nProposed optimization:\n- Add externalRefToID map[string]string to MemoryStorage\n- Maintain it in CreateIssue, UpdateIssue, DeleteIssue\n- Achieve O(1) lookup like SQLite's index\n\nImpact: Low (--no-db mode typically has smaller datasets)\nRelated: bd-1022","status":"closed","priority":4,"issue_type":"chore","created_at":"2025-11-02T15:32:30.242357-08:00","updated_at":"2025-11-26T11:14:49.172418-08:00","closed_at":"2025-11-26T11:14:49.172418-08:00"}
|
||||
{"id":"bd-9li4","title":"Create Docker image for Agent Mail","description":"Containerize Agent Mail server for easy deployment.\n\nAcceptance Criteria:\n- Dockerfile with Python 3.14\n- Health check endpoint\n- Volume mount for storage\n- Environment variable configuration\n- Multi-arch builds (amd64, arm64)\n\nFile: deployment/agent-mail/Dockerfile","status":"closed","priority":3,"issue_type":"task","created_at":"2025-11-07T22:43:43.231964-08:00","updated_at":"2025-11-25T17:47:30.777486-08:00","closed_at":"2025-11-25T17:47:30.777486-08:00"}
|
||||
{"id":"bd-b8h","title":"Refactor check-health DB access to avoid repeated path resolution","description":"The runCheckHealth lightweight checks (hintsDisabled, checkVersionMismatch, checkSyncBranchQuick) each have duplicated database path resolution logic. Extract a helper function to DRY this up.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:35.075929-08:00","updated_at":"2025-11-25T19:50:21.272961-08:00","closed_at":"2025-11-25T19:50:21.272961-08:00"}
|
||||
{"id":"bd-bgs","title":"Git history fallback doesn't escape regex special chars in IDs","description":"## Problem\n\nIn `batchCheckGitHistory`, IDs are directly interpolated into a regex pattern:\n\n```go\npatterns = append(patterns, fmt.Sprintf(\\`\"id\":\"%s\"\\`, id))\nsearchPattern := strings.Join(patterns, \"|\")\ncmd := exec.Command(\"git\", \"log\", \"--all\", \"-G\", searchPattern, ...)\n```\n\nIf an ID contains regex special characters (e.g., `bd-foo.bar` or `bd-test+1`), the pattern will be malformed or match unintended strings.\n\n## Location\n`internal/importer/importer.go:923-926`\n\n## Impact\n- False positives: IDs with `.` could match any character\n- Regex errors: IDs with `[` or `(` could cause git to fail\n- Security: potential for regex injection (low risk since IDs are validated)\n\n## Fix\nEscape regex special characters:\n\n```go\nimport \"regexp\"\n\nescapedID := regexp.QuoteMeta(id)\npatterns = append(patterns, fmt.Sprintf(\\`\"id\":\"%s\"\\`, escapedID))\n```","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:50:30.132232-08:00","updated_at":"2025-11-25T15:04:06.217695-08:00","closed_at":"2025-11-25T15:04:06.217695-08:00"}
|
||||
@@ -18,10 +23,11 @@
|
||||
{"id":"bd-c362","title":"Extract database search logic into helper function","description":"The logic for finding a database in a beads directory is duplicated:\n- FindDatabasePath() BEADS_DIR section (beads.go:141-169)\n- findDatabaseInTree() (beads.go:248-280)\n\nBoth implement the same search order:\n1. Check config.json first (single source of truth)\n2. Fall back to canonical beads.db\n3. Search for *.db files, filtering backups and vc.db\n\nRefactoring suggestion:\nExtract to a helper function like:\n func findDatabaseInBeadsDir(beadsDir string) string\n\nBenefits:\n- Single source of truth for database search logic\n- Easier to maintain and update search order\n- Reduces code duplication\n\nRelated to [deleted:bd-e16b] implementation.","status":"closed","priority":3,"issue_type":"chore","created_at":"2025-11-02T18:34:02.831543-08:00","updated_at":"2025-11-25T22:27:33.794656-08:00","closed_at":"2025-11-25T22:27:33.794656-08:00"}
|
||||
{"id":"bd-c4rq","title":"Refactor: Move staleness check inside daemon branch","description":"## Problem\n\nCurrently ensureDatabaseFresh() is called before the daemon mode check, but it checks daemonClient != nil internally and returns early. This is redundant.\n\n**Location:** All read commands (list.go:196, show.go:27, ready.go:102, status.go:80, etc.)\n\n## Current Pattern\n\nCall happens before daemon check, function checks daemonClient internally.\n\n## Better Pattern\n\nMove staleness check to direct mode branch only, after daemon check.\n\n## Impact\nLow - minor performance improvement (avoids one function call per command in daemon mode)\n\n## Effort\nMedium - requires refactoring 8 command files\n\n## Priority\nLow - can defer to future cleanup PR","status":"open","priority":3,"issue_type":"chore","created_at":"2025-11-20T20:17:45.119583-05:00","updated_at":"2025-11-20T20:17:45.119583-05:00"}
|
||||
{"id":"bd-d4i","title":"Create tip system infrastructure for contextual hints","description":"Implement a tip/hint system that shows helpful contextual messages after successful commands. This is different from the existing error-path \"Hint:\" messages - tips appear on success paths to educate users about features they might not know about.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-11T23:29:15.693956-08:00","updated_at":"2025-11-25T17:47:30.747566-08:00","closed_at":"2025-11-25T17:47:30.747566-08:00"}
|
||||
{"id":"bd-e166","title":"Improve timestamp comparison readability in import","description":"The timestamp comparison logic uses double-negative which can be confusing:\n\nCurrent code:\nif !incoming.UpdatedAt.After(existing.UpdatedAt) {\n // skip update\n}\n\nMore readable:\nif incoming.UpdatedAt.After(existing.UpdatedAt) {\n // perform update\n} else {\n // skip (local is newer)\n}\n\nThis is a minor refactor for code clarity.\n\nRelated: bd-1022\nFiles: internal/importer/importer.go:411, 488","status":"open","priority":4,"issue_type":"chore","created_at":"2025-11-02T15:32:12.27108-08:00","updated_at":"2025-11-02T15:32:12.27108-08:00"}
|
||||
{"id":"bd-e166","title":"Improve timestamp comparison readability in import","description":"The timestamp comparison logic uses double-negative which can be confusing:\n\nCurrent code:\nif !incoming.UpdatedAt.After(existing.UpdatedAt) {\n // skip update\n}\n\nMore readable:\nif incoming.UpdatedAt.After(existing.UpdatedAt) {\n // perform update\n} else {\n // skip (local is newer)\n}\n\nThis is a minor refactor for code clarity.\n\nRelated: bd-1022\nFiles: internal/importer/importer.go:411, 488","status":"closed","priority":4,"issue_type":"chore","created_at":"2025-11-02T15:32:12.27108-08:00","updated_at":"2025-11-26T22:25:27.124071-08:00","closed_at":"2025-11-26T22:25:27.124071-08:00"}
|
||||
{"id":"bd-e92","title":"Add test coverage for internal/autoimport package","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:22.338577-05:00","updated_at":"2025-11-20T21:21:22.338577-05:00","dependencies":[{"issue_id":"bd-e92","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.128625-05:00","created_by":"daemon"}]}
|
||||
{"id":"bd-f0n","title":"Git history fallback missing timeout - could hang on large repos","description":"## Problem\n\nThe git commands in `checkGitHistoryForDeletions` have no timeout. On large repos with extensive history, `git log --all -S` or `git log --all -G` can take a very long time (minutes).\n\n## Location\n`internal/importer/importer.go:899` and `:930`\n\n## Impact\n- Import could hang indefinitely\n- User has no feedback that git search is running\n- No way to cancel except killing the process\n\n## Fix\nAdd context with timeout to git commands:\n\n```go\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\ncmd := exec.CommandContext(ctx, \"git\", ...)\n```\n\nAlso consider adding a `--since` flag to bound the git history search.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:48:24.388639-08:00","updated_at":"2025-11-25T15:04:53.669714-08:00","closed_at":"2025-11-25T15:04:53.669714-08:00"}
|
||||
{"id":"bd-ge7","title":"Improve Beads test coverage from 46% to 80%","description":"","status":"open","priority":1,"issue_type":"epic","created_at":"2025-11-20T21:21:03.700271-05:00","updated_at":"2025-11-20T21:21:03.700271-05:00"}
|
||||
{"id":"bd-ghb","title":"Add --yes flag to bd doctor --fix for non-interactive mode","description":"## Feature Request\n\nAdd a `--yes` or `-y` flag to `bd doctor --fix` that automatically confirms all prompts, enabling non-interactive usage in scripts and CI/CD pipelines.\n\n## Current Behavior\n`bd doctor --fix` prompts for confirmation before applying fixes, which blocks automated workflows.\n\n## Desired Behavior\n`bd doctor --fix --yes` should apply all fixes without prompting.\n\n## Use Cases\n- CI/CD pipelines that need to auto-fix issues\n- Scripts that automate repository setup\n- Pre-commit hooks that want to silently fix issues","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-26T23:22:45.486584-08:00","updated_at":"2025-11-26T23:22:45.486584-08:00"}
|
||||
{"id":"bd-gqo","title":"Implement health checks in daemon event loop","description":"Add health checks to checkDaemonHealth() function in daemon_event_loop.go:170:\n- Database integrity check\n- Disk space check\n- Memory usage check\n\nCurrently it's just a no-op placeholder.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-21T18:55:07.534304-05:00","updated_at":"2025-11-21T18:55:07.534304-05:00"}
|
||||
{"id":"bd-hdt","title":"Implement auto-merge functionality in duplicates command","description":"The duplicates.go file has a TODO at line 95 to implement the performMerge function for automatic duplicate merging. Currently it just prints a warning message. This would automate the merge process instead of just suggesting commands.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-21T18:55:02.828619-05:00","updated_at":"2025-11-21T18:55:02.828619-05:00"}
|
||||
{"id":"bd-imj","title":"Deletion propagation via deletions manifest","description":"## Problem\n\nWhen `bd cleanup -f` or `bd delete` removes issues in one clone, those deletions don't propagate to other clones. The import logic only creates/updates, never deletes. This causes \"resurrection\" where deleted issues reappear.\n\n## Root Cause\n\nImport sees DB issues not in JSONL and assumes they're \"local unpushed work\" rather than \"intentionally deleted upstream.\"\n\n## Solution: Deletions Manifest\n\nAdd `.beads/deletions.jsonl` - an append-only log of deleted issue IDs with metadata.\n\n### Format\n```jsonl\n{\"id\":\"bd-xxx\",\"ts\":\"2025-11-25T10:00:00Z\",\"by\":\"stevey\"}\n{\"id\":\"bd-yyy\",\"ts\":\"2025-11-25T10:05:00Z\",\"by\":\"claude\",\"reason\":\"duplicate of bd-zzz\"}\n```\n\n### Fields\n- `id`: Issue ID (required)\n- `ts`: ISO 8601 UTC timestamp (required)\n- `by`: Actor who deleted (required)\n- `reason`: Optional context (\"cleanup\", \"duplicate of X\", etc.)\n\n### Import Logic\n```\nFor each DB issue not in JSONL:\n 1. Check deletions manifest → if found, delete from DB\n 2. Fallback: check git history → if found, delete + backfill manifest\n 3. Neither → keep (local unpushed work)\n```\n\n### Conflict Resolution\nSimultaneous deletions from multiple clones are handled naturally:\n- Append-only design means both clones append their deletion records\n- On merge, file contains duplicate entries (same ID, different timestamps)\n- `LoadDeletions` deduplicates by ID (keeps any/first entry)\n- Result: deletion propagates correctly, duplicates are harmless\n\n### Pruning Policy\n- Default retention: 7 days (configurable via `deletions.retention_days`)\n- Auto-compact during `bd sync` is **opt-in** (disabled by default)\n- Hard cap: `deletions.max_entries` (default 50000)\n- Git fallback handles pruned entries (self-healing)\n\n### Self-Healing\nWhen git fallback catches a resurrection (pruned entry), it backfills the manifest. One-time git scan cost, then fast again.\n\n### Size Estimates\n- ~80 bytes/entry\n- 7-day retention with 100 deletions/day = ~56KB\n- Git compressed: ~10KB\n\n## Benefits\n- ✅ Deletions propagate across clones\n- ✅ O(1) lookup (no git scan in normal case)\n- ✅ Works in shallow clones\n- ✅ Survives history rewrite\n- ✅ Audit trail (who deleted what when)\n- ✅ Self-healing via git fallback\n- ✅ Bounded size via time-based pruning\n\n## References\n- Investigation session: 2025-11-25\n- Related: bd-2q6d (stale database warnings)","status":"closed","priority":0,"issue_type":"epic","created_at":"2025-11-25T09:56:01.98027-08:00","updated_at":"2025-11-25T16:36:27.965168-08:00","closed_at":"2025-11-25T16:36:27.965168-08:00","dependencies":[{"issue_id":"bd-imj","depends_on_id":"bd-qsm","type":"blocks","created_at":"2025-11-25T09:57:42.821911-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-x2i","type":"blocks","created_at":"2025-11-25T09:57:42.851712-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-44e","type":"blocks","created_at":"2025-11-25T09:57:42.88154-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-bhd","type":"blocks","created_at":"2025-11-25T14:56:23.675787-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-bgs","type":"blocks","created_at":"2025-11-25T14:56:23.744648-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-f0n","type":"blocks","created_at":"2025-11-25T14:56:23.80649-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-v29","type":"blocks","created_at":"2025-11-25T14:56:23.864569-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-mdw","type":"blocks","created_at":"2025-11-25T14:56:48.592492-08:00","created_by":"daemon"},{"issue_id":"bd-imj","depends_on_id":"bd-03r","type":"blocks","created_at":"2025-11-25T14:56:54.295851-08:00","created_by":"daemon"}]}
|
||||
@@ -33,19 +39,21 @@
|
||||
{"id":"bd-m7ge","title":"Add .beads/README.md during 'bd init' for project documentation and promotion","description":"When 'bd init' is run, automatically generate a .beads/README.md file that:\n\n1. Briefly explains what Beads is (AI-native issue tracking that lives in your repo)\n2. Links to the main repository: https://github.com/steveyegge/beads\n3. Provides a quick reference of essential commands:\n - bd create: Create new issues\n - bd list: View all issues\n - bd update: Modify issue status/details\n - bd show: View issue details\n - bd sync: Sync with git remote\n4. Highlights key benefits for AI coding agents and developers\n5. Encourages developers to try it out\n\nThe README should be enthusiastic and compelling to get open source contributors excited about using Beads for their AI-assisted development workflows.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-16T22:32:50.478681-08:00","updated_at":"2025-11-25T17:49:42.558381-08:00","closed_at":"2025-11-25T17:49:42.558381-08:00"}
|
||||
{"id":"bd-mdw","title":"Add integration test for cross-clone deletion propagation","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T14:56:38.997009-08:00","updated_at":"2025-11-25T16:35:59.052914-08:00","closed_at":"2025-11-25T16:35:59.052914-08:00"}
|
||||
{"id":"bd-mnap","title":"Investigate performance issues in VS Code Copilot (Windows)","description":"Beads unusable in Windows 11 VS Code Copilot chat with Sonnet 4.5.\nSummary event happens every 3-4 turns, taking 3 minutes.\nCopilot summarizes after ~125k tokens despite model supporting 1M.\nLarge context size of beads might be triggering aggressive summarization.\nNeed workaround or optimization for context size.\n","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:30.124918-05:00","updated_at":"2025-11-20T18:56:30.124918-05:00"}
|
||||
{"id":"bd-nq41","title":"Fix Homebrew warning about Ruby file location","description":"Homebrew warning: Found Ruby file outside steveyegge/beads tap formula directory.\nWarning points to: /opt/homebrew/Library/Taps/steveyegge/homebrew-beads/bd.rb\nIt should likely be inside a Formula/ directory or similar structure expected by Homebrew taps.\n","status":"open","priority":2,"issue_type":"chore","created_at":"2025-11-20T18:56:21.226579-05:00","updated_at":"2025-11-20T18:56:21.226579-05:00"}
|
||||
{"id":"bd-p6vp","title":"Clarify .beads/.gitattributes handling in Protected Branches docs","description":"Protected Branches docs quick start leaves untracked `.beads` directory and `.gitattributes`.\nQuestion: Are these changes meant to be checked into the protected branch?\nNeed to clarify if these should be ignored or committed, or if the instructions are missing a step.\n","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:25.79407-05:00","updated_at":"2025-11-20T18:56:25.79407-05:00"}
|
||||
{"id":"bd-nq41","title":"Fix Homebrew warning about Ruby file location","description":"Homebrew warning: Found Ruby file outside steveyegge/beads tap formula directory.\nWarning points to: /opt/homebrew/Library/Taps/steveyegge/homebrew-beads/bd.rb\nIt should likely be inside a Formula/ directory or similar structure expected by Homebrew taps.\n","status":"closed","priority":2,"issue_type":"chore","created_at":"2025-11-20T18:56:21.226579-05:00","updated_at":"2025-11-26T22:25:37.362928-08:00","closed_at":"2025-11-26T22:25:37.362928-08:00"}
|
||||
{"id":"bd-p6vp","title":"Clarify .beads/.gitattributes handling in Protected Branches docs","description":"Protected Branches docs quick start leaves untracked `.beads` directory and `.gitattributes`.\nQuestion: Are these changes meant to be checked into the protected branch?\nNeed to clarify if these should be ignored or committed, or if the instructions are missing a step.\n","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:25.79407-05:00","updated_at":"2025-11-26T22:25:47.574326-08:00","closed_at":"2025-11-26T22:25:47.574326-08:00"}
|
||||
{"id":"bd-qsm","title":"Auto-compact deletions during bd sync","description":"Parent: bd-imj\n\n## Task\nOptionally prune deletions manifest during sync when threshold exceeded.\n\n**Note: Opt-in feature** - disabled by default to avoid sync latency.\n\n## Implementation\n\nIn `bd sync`:\n```go\nfunc (s *Syncer) Sync() error {\n // ... existing sync logic ...\n \n // Auto-compact only if enabled\n if s.config.GetBool(\"deletions.auto_compact\", false) {\n deletionCount := deletions.Count(\".beads/deletions.jsonl\")\n threshold := s.config.GetInt(\"deletions.auto_compact_threshold\", 1000)\n \n if deletionCount \u003e threshold {\n retentionDays := s.config.GetInt(\"deletions.retention_days\", 7)\n if err := s.compactor.PruneDeletions(retentionDays); err != nil {\n log.Warnf(\"Failed to auto-compact deletions: %v\", err)\n // Non-fatal, continue sync\n }\n }\n }\n \n // ... rest of sync ...\n}\n```\n\n## Configuration\n```yaml\ndeletions:\n retention_days: 7\n auto_compact: false # Opt-in, disabled by default\n auto_compact_threshold: 1000 # Trigger when \u003e N entries (if enabled)\n```\n\n## Acceptance Criteria\n- [ ] Auto-compact disabled by default\n- [ ] Enabled via config `deletions.auto_compact: true`\n- [ ] Sync checks deletion count only when enabled\n- [ ] Auto-prunes when threshold exceeded\n- [ ] Failure is non-fatal (logged warning)\n- [ ] Test: no compaction when disabled\n- [ ] Test: compaction triggers when enabled and threshold exceeded","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-25T09:57:04.522795-08:00","updated_at":"2025-11-25T15:03:01.469629-08:00","closed_at":"2025-11-25T15:03:01.469629-08:00"}
|
||||
{"id":"bd-s0z","title":"Consider extracting error handling helpers","description":"Evaluate creating FatalError() and WarnError() helpers as suggested in ERROR_HANDLING.md to reduce boilerplate and enforce consistency. Prototype in a few files first to validate the approach.","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-24T00:28:57.248959-08:00","updated_at":"2025-11-24T00:28:57.248959-08:00"}
|
||||
{"id":"bd-t3b","title":"Add test coverage for internal/config package","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:22.91657-05:00","updated_at":"2025-11-20T21:21:22.91657-05:00","dependencies":[{"issue_id":"bd-t3b","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.201036-05:00","created_by":"daemon"}]}
|
||||
{"id":"bd-tne","title":"Add Claude setup tip with dynamic priority","description":"Add a predefined tip that suggests running `bd setup claude` when Claude Code is detected but not configured. This tip should have higher priority (shown more frequently) until the setup is complete.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:29:29.871324-08:00","updated_at":"2025-11-25T17:52:35.044989-08:00","closed_at":"2025-11-25T17:52:35.044989-08:00","dependencies":[{"issue_id":"bd-tne","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:29.872081-08:00","created_by":"daemon"}]}
|
||||
{"id":"bd-tqo","title":"deletions.jsonl gets corrupted with full issue objects instead of deletion records","description":"## Bug Description\n\nThe deletions.jsonl file was found to contain full issue objects (like issues.jsonl) instead of deletion records.\n\n### Expected Format (DeletionRecord)\n```json\n{\"id\":\"bd-xxx\",\"timestamp\":\"2025-...\",\"actor\":\"user\",\"reason\":\"deleted\"}\n```\n\n### Actual Content Found\n```json\n{\"id\":\"bd-03r\",\"title\":\"Document deletions manifest...\",\"description\":\"...\",\"status\":\"closed\",...}\n```\n\n## Impact\n- bd sync sanitization step reads deletions.jsonl and removes any matching IDs from issues.jsonl\n- With 60 full issue objects in deletions.jsonl, ALL 60 issues were incorrectly removed during sync\n- This caused complete data loss of the issue database\n\n## Root Cause (suspected)\nSomething wrote issues.jsonl content to deletions.jsonl. Possible causes:\n- Export writing to wrong file\n- File path confusion during sync\n- Race condition between export and deletion tracking\n\n## Related Issues\n- bd-0b2: --no-git-history flag (just fixed)\n- bd-4pv: export outputs only 1 issue after corruption \n- bd-4t7: auto-import runs during --no-auto-import\n\n## Reproduction\nUnknown - discovered during bd sync session on 2025-11-26\n\n## Fix\nNeed to investigate what code path could write issue objects to deletions.jsonl","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-26T23:17:01.938931-08:00","updated_at":"2025-11-26T23:25:02.209911-08:00","closed_at":"2025-11-26T23:25:02.209911-08:00"}
|
||||
{"id":"bd-tru","title":"Update documentation for bd prime and Claude integration","description":"Update AGENTS.md, README.md, and QUICKSTART.md to document the new `bd prime` command, `bd setup claude` command, and tip system.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:30:22.77349-08:00","updated_at":"2025-11-25T17:47:30.807069-08:00","closed_at":"2025-11-25T17:47:30.807069-08:00"}
|
||||
{"id":"bd-tys","title":"Git history fallback has incorrect logic for detecting deletions","description":"## Problem\n\nThe `wasInGitHistory` function in `internal/importer/importer.go:891` returns true if the ID is found **anywhere** in git history. But finding an ID in history doesn't necessarily mean it was deleted - it could mean:\n\n1. The issue was added (appears in a commit adding it)\n2. The issue was modified (appears in commits updating it)\n3. The issue was deleted (appears in a commit removing it)\n\nThe current logic incorrectly treats all three cases as 'deleted'.\n\n## Correct Logic\n\n`git log -S` with `--oneline` shows commits where the string was added OR removed. To detect deletion specifically:\n\n1. ID appears in git history (was once in JSONL)\n2. ID is NOT currently in JSONL\n\nThe second condition is already checked by the caller (`purgeDeletedIssues`), so technically the logic is correct in context. But the function name and doc comment are misleading.\n\n## Fix Options\n\n1. **Rename function** to `wasEverInJSONL` and update doc comment to clarify\n2. **Add explicit check** for current JSONL state in the function itself\n\nOption 1 is simpler and correct since caller already filters.","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:46:16.073661-08:00","updated_at":"2025-11-25T15:11:54.426093-08:00","closed_at":"2025-11-25T15:11:54.426093-08:00"}
|
||||
{"id":"bd-v29","title":"Deletions pruning doesn't include results in JSON output","description":"## Problem\n\nWhen `bd compact --json` runs with deletions pruning, the prune results are silently discarded:\n\n```go\n// Only report if there were deletions to prune\nif result.PrunedCount \u003e 0 {\n if jsonOutput {\n // JSON output will be included in the main response\n return // \u003c-- BUG: results are NOT included anywhere\n }\n ...\n}\n```\n\n## Location\n`cmd/bd/compact.go:925-929`\n\n## Impact\n- JSON consumers don't know deletions were pruned\n- No way to audit pruning via automation\n\n## Fix\nReturn prune results and include in JSON output structure:\n\n```json\n{\n \"success\": true,\n \"compacted\": {...},\n \"deletions_pruned\": {\n \"count\": 5,\n \"retention_days\": 7\n }\n}\n```","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:48:59.730979-08:00","updated_at":"2025-11-25T15:11:54.363653-08:00","closed_at":"2025-11-25T15:11:54.363653-08:00"}
|
||||
{"id":"bd-wcl","title":"Document CLI + hooks as recommended approach over MCP","description":"Update documentation to position CLI + bd prime hooks as the primary recommended approach over MCP server, explaining why minimizing context matters even with large context windows (compute cost, energy, environment, latency).","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-12T00:15:25.923025-08:00","updated_at":"2025-11-12T00:18:16.786857-08:00"}
|
||||
{"id":"bd-wcl","title":"Document CLI + hooks as recommended approach over MCP","description":"Update documentation to position CLI + bd prime hooks as the primary recommended approach over MCP server, explaining why minimizing context matters even with large context windows (compute cost, energy, environment, latency).","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-12T00:15:25.923025-08:00","updated_at":"2025-11-26T20:13:52.891053-08:00","closed_at":"2025-11-26T18:06:51.020351-08:00"}
|
||||
{"id":"bd-wmo","title":"PruneDeletions iterates map non-deterministically","description":"## Problem\n\n`PruneDeletions` iterates over `loadResult.Records` which is a map. Go maps iterate in random order, so:\n\n1. `result.PrunedIDs` order is non-deterministic\n2. `kept` slice order is non-deterministic → `WriteDeletions` output order varies\n\n## Location\n`internal/deletions/deletions.go:213`\n\n## Impact\n- Git diffs are noisy (file changes order on each prune)\n- Tests could be flaky if they depend on order\n- Harder to debug/audit\n\n## Fix\nSort by ID or timestamp before iterating:\n\n```go\n// Convert map to slice and sort\nvar records []DeletionRecord\nfor _, r := range loadResult.Records {\n records = append(records, r)\n}\nsort.Slice(records, func(i, j int) bool {\n return records[i].ID \u003c records[j].ID\n})\n```","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:49:11.290916-08:00","updated_at":"2025-11-25T15:15:21.903649-08:00","closed_at":"2025-11-25T15:15:21.903649-08:00"}
|
||||
{"id":"bd-x2i","title":"Add bd deleted command for audit trail","description":"Parent: bd-imj\n\nAdd command to view deletion history.\n\nUsage:\n bd deleted # Show recent deletions (last 7 days)\n bd deleted --since=30d # Show deletions in last 30 days\n bd deleted --all # Show all tracked deletions\n bd deleted bd-xxx # Show deletion details for specific issue\n\nOutput format:\n bd-xxx 2025-11-25 10:00 stevey duplicate of bd-yyy\n bd-yyy 2025-11-25 10:05 claude cleanup\n\nAcceptance criteria:\n- List deletions with timestamp, actor, reason\n- Filter by time range\n- Lookup specific issue ID\n- JSON output option for scripting","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T09:57:21.113861-08:00","updated_at":"2025-11-25T15:13:53.781519-08:00","closed_at":"2025-11-25T15:13:53.781519-08:00"}
|
||||
{"id":"bd-xyc","title":"Consolidate check-health DB opens into single connection","description":"The --check-health flag opens the database 3 separate times (once per quick check). Consolidate into a single DB open for better performance, especially on slower filesystems.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:42.034178-08:00","updated_at":"2025-11-25T19:50:21.32375-08:00","closed_at":"2025-11-25T19:50:21.32375-08:00"}
|
||||
{"id":"bd-ybv5","title":"Refactor AGENTS.md to use external references","description":"Suggestion to use external references (e.g., \"ALWAYS REFER TO ./beads/prompt.md\") instead of including all instructions directly within AGENTS.md.\nReasons:\n1. Agents can follow external references.\n2. Prevents context pollution/stuffing in AGENTS.md as more tools append instructions.\n","status":"open","priority":3,"issue_type":"task","created_at":"2025-11-20T18:55:53.259144-05:00","updated_at":"2025-11-20T18:55:53.259144-05:00"}
|
||||
{"id":"bd-ybv5","title":"Refactor AGENTS.md to use external references","description":"Suggestion to use external references (e.g., \"ALWAYS REFER TO ./beads/prompt.md\") instead of including all instructions directly within AGENTS.md.\nReasons:\n1. Agents can follow external references.\n2. Prevents context pollution/stuffing in AGENTS.md as more tools append instructions.\n","status":"closed","priority":3,"issue_type":"task","created_at":"2025-11-20T18:55:53.259144-05:00","updated_at":"2025-11-26T22:25:57.772875-08:00","closed_at":"2025-11-26T22:25:57.772875-08:00"}
|
||||
{"id":"bd-ye0d","title":"troubleshoot GH#278 daemon exits every few secs","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-13T06:27:23.39509215-07:00","updated_at":"2025-11-25T17:48:43.62418-08:00","closed_at":"2025-11-25T17:48:43.62418-08:00"}
|
||||
{"id":"bd-zai","title":"bd init resets metadata.json jsonl_export to beads.jsonl, ignoring existing issues.jsonl","description":"When running 'bd init --prefix bd' in a repo that already has .beads/issues.jsonl, the init command overwrites metadata.json and sets jsonl_export back to 'beads.jsonl' instead of detecting and respecting the existing issues.jsonl file.\n\nSteps to reproduce:\n1. Have a repo with .beads/issues.jsonl (canonical) and metadata.json pointing to issues.jsonl\n2. Delete beads.db and run 'bd init --prefix bd'\n3. Check metadata.json - it now says jsonl_export: beads.jsonl\n\nExpected: Init should detect existing issues.jsonl and use it.\n\nWorkaround: Manually edit metadata.json after init.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:27:41.653287-08:00","updated_at":"2025-11-26T22:27:41.653287-08:00"}
|
||||
{"id":"bd-zj8e","title":"Performance Testing Documentation","description":"Create docs/performance-testing.md documenting the performance testing framework.\n\nSections:\n1. Overview - What the framework does, goals\n2. Running Benchmarks\n - make bench command\n - Running specific benchmarks\n - Interpreting output (ns/op, allocs/op)\n3. Profiling and Analysis\n - Viewing CPU profiles with pprof\n - Reading flamegraphs\n - Memory profiling\n - Finding hotspots\n4. User Diagnostics\n - bd doctor --perf usage\n - Sharing profiles with bug reports\n - Understanding the report output\n5. Comparing Performance\n - Using benchstat for before/after comparisons\n - Detecting regressions\n6. Tips for Optimization\n - Common patterns\n - When to profile vs benchmark\n\nStyle:\n- Concise, practical examples\n- Screenshots/examples of pprof output\n- Clear command-line examples\n- Focus on workflow, not theory","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-13T22:23:38.99897-08:00","updated_at":"2025-11-13T22:23:38.99897-08:00"}
|
||||
|
||||
@@ -1,477 +1,559 @@
|
||||
# CLI Reference
|
||||
# CLI Command Reference
|
||||
|
||||
Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output.
|
||||
**For:** AI agents and developers using bd command-line interface
|
||||
**Version:** 0.21.0+
|
||||
|
||||
## Contents
|
||||
## Quick Navigation
|
||||
|
||||
- [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
|
||||
- [Data Management Commands](#data-management-commands)
|
||||
- [bd export](#bd-export) - Export database to JSONL
|
||||
- [bd import](#bd-import) - Import issues from JSONL
|
||||
- [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)
|
||||
- [Basic Operations](#basic-operations)
|
||||
- [Issue Management](#issue-management)
|
||||
- [Dependencies & Labels](#dependencies--labels)
|
||||
- [Filtering & Search](#filtering--search)
|
||||
- [Advanced Operations](#advanced-operations)
|
||||
- [Database Management](#database-management)
|
||||
|
||||
## Quick Reference
|
||||
## Basic Operations
|
||||
|
||||
| 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 export` | Export issues to JSONL | `--json` |
|
||||
| `bd import` | Import issues from JSONL | `--dedupe-after`, `--dry-run` |
|
||||
| `bd init` | Initialize bd in directory | `--prefix` |
|
||||
| `bd quickstart` | Show quick start guide | (no flags) |
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Check database path and daemon status
|
||||
bd info --json
|
||||
|
||||
# Example output:
|
||||
# {
|
||||
# "database_path": "/path/to/.beads/beads.db",
|
||||
# "issue_prefix": "bd",
|
||||
# "daemon_running": true,
|
||||
# "agent_mail_enabled": false
|
||||
# }
|
||||
```
|
||||
|
||||
### Find Work
|
||||
|
||||
```bash
|
||||
# Find ready work (no blockers)
|
||||
bd ready --json
|
||||
|
||||
# Find stale issues (not updated recently)
|
||||
bd stale --days 30 --json # Default: 30 days
|
||||
bd stale --days 90 --status in_progress --json # Filter by status
|
||||
bd stale --limit 20 --json # Limit results
|
||||
```
|
||||
|
||||
## Issue Management
|
||||
|
||||
### Create Issues
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
# Create multiple issues from markdown file
|
||||
bd create -f feature-plan.md --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 --json # Auto-assigned: bd-a3f8e9.1
|
||||
bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2
|
||||
bd create "Tests" -p 1 --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
|
||||
```
|
||||
|
||||
### Update Issues
|
||||
|
||||
```bash
|
||||
# Update one or more issues
|
||||
bd update <id> [<id>...] --status in_progress --json
|
||||
bd update <id> [<id>...] --priority 1 --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
|
||||
```
|
||||
|
||||
### Close/Reopen Issues
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### View Issues
|
||||
|
||||
```bash
|
||||
# Show dependency tree
|
||||
bd dep tree <id>
|
||||
|
||||
# Get issue details (supports multiple IDs)
|
||||
bd show <id> [<id>...] --json
|
||||
```
|
||||
|
||||
## Dependencies & Labels
|
||||
|
||||
### Dependencies
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Labels
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
## Filtering & Search
|
||||
|
||||
### Basic Filters
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Label Filters
|
||||
|
||||
```bash
|
||||
# Labels (AND: must have ALL)
|
||||
bd list --label bug,critical --json
|
||||
|
||||
# Labels (OR: has ANY)
|
||||
bd list --label-any frontend,backend --json
|
||||
```
|
||||
|
||||
### Text Search
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Date Range Filters
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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 Filters
|
||||
|
||||
```bash
|
||||
# Combine multiple filters
|
||||
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
|
||||
```
|
||||
|
||||
## Global Flags
|
||||
|
||||
Available for all commands:
|
||||
Global flags work with any bd command and must appear **before** the subcommand.
|
||||
|
||||
### Sandbox Mode
|
||||
|
||||
**Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode.
|
||||
|
||||
When detected, you'll see: `ℹ️ Sandbox detected, using direct mode`
|
||||
|
||||
**Manual override:**
|
||||
|
||||
```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
|
||||
# Explicitly enable sandbox mode
|
||||
bd --sandbox <command>
|
||||
|
||||
# Equivalent to combining these flags:
|
||||
bd --no-daemon --no-auto-flush --no-auto-import <command>
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
**What it does:**
|
||||
- Disables daemon (uses direct SQLite mode)
|
||||
- Disables auto-export to JSONL
|
||||
- Disables auto-import from JSONL
|
||||
|
||||
### bd ready
|
||||
**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger.
|
||||
|
||||
Find tasks with no blockers - ready to be worked on.
|
||||
### Staleness Control
|
||||
|
||||
```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
|
||||
# Skip staleness check (emergency escape hatch)
|
||||
bd --allow-stale <command>
|
||||
|
||||
# Example: access database even if out of sync with JSONL
|
||||
bd --allow-stale ready --json
|
||||
bd --allow-stale list --status open --json
|
||||
```
|
||||
|
||||
**Use at session start** to see available work.
|
||||
**Shows:** `⚠️ Staleness check skipped (--allow-stale), data may be out of sync`
|
||||
|
||||
---
|
||||
**⚠️ Caution:** May show stale or incomplete data. Use only when stuck and other options fail.
|
||||
|
||||
### bd create
|
||||
|
||||
Create a new issue with optional metadata.
|
||||
### Force Import
|
||||
|
||||
```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
|
||||
# Force metadata update even when DB appears synced
|
||||
bd import --force -i .beads/beads.jsonl
|
||||
```
|
||||
|
||||
**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
|
||||
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.
|
||||
|
||||
---
|
||||
**Shows:** `Metadata updated (database already in sync with JSONL)`
|
||||
|
||||
### bd update
|
||||
|
||||
Update an existing issue's metadata.
|
||||
### Other Global Flags
|
||||
|
||||
```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"
|
||||
# JSON output for programmatic use
|
||||
bd --json <command>
|
||||
|
||||
# Force direct mode (bypass daemon)
|
||||
bd --no-daemon <command>
|
||||
|
||||
# Disable auto-sync
|
||||
bd --no-auto-flush <command> # Disable auto-export to JSONL
|
||||
bd --no-auto-import <command> # Disable auto-import from JSONL
|
||||
|
||||
# Custom database path
|
||||
bd --db /path/to/.beads/beads.db <command>
|
||||
|
||||
# Custom actor for audit trail
|
||||
bd --actor alice <command>
|
||||
```
|
||||
|
||||
**Status values**: open, in_progress, blocked, closed
|
||||
**See also:**
|
||||
- [TROUBLESHOOTING.md - Sandboxed environments](TROUBLESHOOTING.md#sandboxed-environments-codex-claude-code-etc) for detailed sandbox troubleshooting
|
||||
- [DAEMON.md](DAEMON.md) for daemon mode details
|
||||
|
||||
---
|
||||
## Advanced Operations
|
||||
|
||||
### bd close
|
||||
|
||||
Close (complete) an issue.
|
||||
### Cleanup
|
||||
|
||||
```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"
|
||||
# Clean up closed issues (bulk deletion)
|
||||
bd cleanup --force --json # Delete ALL closed issues
|
||||
bd cleanup --older-than 30 --force --json # Delete closed >30 days ago
|
||||
bd cleanup --dry-run --json # Preview what would be deleted
|
||||
bd cleanup --older-than 90 --cascade --force --json # Delete old + dependents
|
||||
```
|
||||
|
||||
**Note**: Closed issues remain in database for history.
|
||||
|
||||
---
|
||||
|
||||
### bd show
|
||||
|
||||
Show detailed information about a specific issue.
|
||||
### Duplicate Detection & Merging
|
||||
|
||||
```bash
|
||||
bd show issue-123
|
||||
bd show issue-123 --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
|
||||
```
|
||||
|
||||
Shows: all fields, dependencies, dependents, audit history.
|
||||
|
||||
---
|
||||
|
||||
### bd list
|
||||
|
||||
List all issues with optional filters.
|
||||
### Compaction (Memory Decay)
|
||||
|
||||
```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
|
||||
# Agent-driven compaction
|
||||
bd compact --analyze --json # Get candidates for review
|
||||
bd compact --analyze --tier 1 --limit 10 --json # Limited batch
|
||||
bd compact --apply --id bd-42 --summary summary.txt # Apply compaction
|
||||
bd compact --apply --id bd-42 --summary - < summary.txt # From stdin
|
||||
bd compact --stats --json # Show statistics
|
||||
|
||||
# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
|
||||
bd compact --auto --dry-run --all # Preview
|
||||
bd 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Commands
|
||||
|
||||
### bd dep add
|
||||
|
||||
Add a dependency between issues.
|
||||
### Rename Prefix
|
||||
|
||||
```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
|
||||
# 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
|
||||
```
|
||||
|
||||
**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
|
||||
## Database Management
|
||||
|
||||
---
|
||||
|
||||
### bd dep tree
|
||||
|
||||
Visualize full dependency tree for an issue.
|
||||
### Import/Export
|
||||
|
||||
```bash
|
||||
bd dep tree issue-123
|
||||
# Import issues from JSONL
|
||||
bd import -i .beads/issues.jsonl --dry-run # Preview changes
|
||||
bd import -i .beads/issues.jsonl # Import and update issues
|
||||
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
|
||||
|
||||
# Handle missing parents during import
|
||||
bd import -i issues.jsonl --orphan-handling allow # Default: import orphans without validation
|
||||
bd import -i issues.jsonl --orphan-handling resurrect # Auto-resurrect deleted parents as tombstones
|
||||
bd import -i issues.jsonl --orphan-handling skip # Skip orphans with warning
|
||||
bd import -i issues.jsonl --orphan-handling strict # Fail if parent is missing
|
||||
|
||||
# Configure default orphan handling behavior
|
||||
bd config set import.orphan_handling "resurrect"
|
||||
bd sync # Now uses resurrect mode by default
|
||||
```
|
||||
|
||||
Shows all dependencies and dependents in tree format.
|
||||
**Orphan handling modes:**
|
||||
|
||||
---
|
||||
- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
|
||||
- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
|
||||
- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
|
||||
- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
|
||||
|
||||
### bd dep cycles
|
||||
**When to use:**
|
||||
- Use `allow` (default) for daily imports and auto-sync
|
||||
- Use `resurrect` when importing from databases with deleted parents
|
||||
- Use `strict` for controlled imports requiring guaranteed parent existence
|
||||
- Use `skip` rarely - only for selective imports
|
||||
|
||||
Detect circular dependencies.
|
||||
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
|
||||
|
||||
### Migration
|
||||
|
||||
```bash
|
||||
bd dep cycles
|
||||
# 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
|
||||
```
|
||||
|
||||
Finds dependency cycles that would prevent work from being ready.
|
||||
**Migration workflow for AI agents:**
|
||||
|
||||
---
|
||||
1. Run `--inspect` to see pending migrations and warnings
|
||||
2. Check for `missing_config` (like issue_prefix)
|
||||
3. Review `invariants_to_check` for safety guarantees
|
||||
4. If warnings exist, fix config issues first
|
||||
5. Then run `bd migrate` safely
|
||||
|
||||
## Monitoring Commands
|
||||
**Migration safety invariants:**
|
||||
|
||||
### bd stats
|
||||
- **required_config_present**: Ensures issue_prefix and schema_version are set
|
||||
- **foreign_keys_valid**: No orphaned dependencies or labels
|
||||
- **issue_count_stable**: Issue count doesn't decrease unexpectedly
|
||||
|
||||
Get project statistics.
|
||||
These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
|
||||
|
||||
### Daemon Management
|
||||
|
||||
See [docs/DAEMON.md](DAEMON.md) for complete daemon management reference.
|
||||
|
||||
```bash
|
||||
bd stats
|
||||
bd stats --json
|
||||
# List all running daemons
|
||||
bd daemons list --json
|
||||
|
||||
# Check health (version mismatches, stale sockets)
|
||||
bd daemons health --json
|
||||
|
||||
# Stop/restart specific daemon
|
||||
bd daemons stop /path/to/workspace --json
|
||||
bd daemons restart 12345 --json # By PID
|
||||
|
||||
# View daemon logs
|
||||
bd daemons logs /path/to/workspace -n 100
|
||||
bd daemons logs 12345 -f # Follow mode
|
||||
|
||||
# Stop all daemons
|
||||
bd daemons killall --json
|
||||
bd daemons killall --force --json # Force kill if graceful fails
|
||||
```
|
||||
|
||||
Returns: total, open, in_progress, closed, blocked, ready, avg lead time.
|
||||
|
||||
---
|
||||
|
||||
### bd blocked
|
||||
|
||||
Get blocked issues with blocker information.
|
||||
### Sync Operations
|
||||
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
# Manual sync (force immediate export/import/commit/push)
|
||||
bd sync
|
||||
|
||||
# What it does:
|
||||
# 1. Export pending changes to JSONL
|
||||
# 2. Commit to git
|
||||
# 3. Pull from remote
|
||||
# 4. Import any updates
|
||||
# 5. Push to remote
|
||||
```
|
||||
|
||||
Use to identify bottlenecks when ready list is empty.
|
||||
## Issue Types
|
||||
|
||||
---
|
||||
- `bug` - Something broken that needs fixing
|
||||
- `feature` - New functionality
|
||||
- `task` - Work item (tests, docs, refactoring)
|
||||
- `epic` - Large feature composed of multiple issues (supports hierarchical children)
|
||||
- `chore` - Maintenance work (dependencies, tooling)
|
||||
|
||||
## Data Management Commands
|
||||
**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported.
|
||||
|
||||
### bd export
|
||||
## Priorities
|
||||
|
||||
Export all issues to JSONL format.
|
||||
- `0` - Critical (security, data loss, broken builds)
|
||||
- `1` - High (major features, important bugs)
|
||||
- `2` - Medium (nice-to-have features, minor bugs)
|
||||
- `3` - Low (polish, optimization)
|
||||
- `4` - Backlog (future ideas)
|
||||
|
||||
## Dependency Types
|
||||
|
||||
- `blocks` - Hard dependency (issue X blocks issue Y)
|
||||
- `related` - Soft relationship (issues are connected)
|
||||
- `parent-child` - Epic/subtask relationship
|
||||
- `discovered-from` - Track issues discovered during work
|
||||
|
||||
Only `blocks` dependencies affect the ready work queue.
|
||||
|
||||
**Note:** When creating an issue with a `discovered-from` dependency, the new issue automatically inherits the parent's `source_repo` field.
|
||||
|
||||
## Output Formats
|
||||
|
||||
### JSON Output (Recommended for Agents)
|
||||
|
||||
Always use `--json` flag for programmatic use:
|
||||
|
||||
```bash
|
||||
bd export > issues.jsonl
|
||||
bd export --json # Same output, explicit flag
|
||||
```
|
||||
# Single issue
|
||||
bd show bd-42 --json
|
||||
|
||||
**Use cases:**
|
||||
- Manual backup before risky operations
|
||||
- Sharing issues across databases
|
||||
- Version control / git tracking
|
||||
- Data migration or analysis
|
||||
|
||||
**Note**: bd auto-exports to `.beads/*.jsonl` after each operation (5s debounce). Manual export is rarely needed.
|
||||
|
||||
---
|
||||
|
||||
### bd import
|
||||
|
||||
Import issues from JSONL format.
|
||||
|
||||
```bash
|
||||
bd import < issues.jsonl
|
||||
bd import -i issues.jsonl --dry-run # Preview changes
|
||||
```
|
||||
|
||||
**Behavior with hash-based IDs (v0.20.1+):**
|
||||
- Same ID = update operation (hash IDs remain stable)
|
||||
- Different issues get different hash IDs (no collisions)
|
||||
- Import automatically applies updates to existing issues
|
||||
|
||||
**Use `--dry-run` to preview:**
|
||||
```bash
|
||||
bd import -i issues.jsonl --dry-run
|
||||
# Shows: new issues, updates, exact matches
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- **Syncing after git pull** - daemon auto-imports, manual rarely needed
|
||||
- **Merging databases** - import issues from another database
|
||||
- **Restoring from backup** - reimport JSONL to restore state
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
# List of issues
|
||||
bd ready --json
|
||||
bd show issue-123
|
||||
bd update issue-123 --status in_progress
|
||||
|
||||
# Operation result
|
||||
bd create "Issue" -p 1 --json
|
||||
```
|
||||
|
||||
### Discovery During Work
|
||||
### Human-Readable Output
|
||||
|
||||
```bash
|
||||
bd create "Found: bug in auth" -t bug
|
||||
bd dep add current-issue new-issue --type discovered-from
|
||||
```
|
||||
Default output without `--json`:
|
||||
|
||||
### 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_DIR` environment variable (points to .beads directory)
|
||||
3. `$BEADS_DB` environment variable (deprecated, points to database file)
|
||||
4. `.beads/*.db` in current directory or ancestors
|
||||
|
||||
**Project-local** (`.beads/`): Project-specific work, git-tracked
|
||||
|
||||
**Recommended**: Use `BEADS_DIR` to point to your `.beads` directory, especially when using `--no-db` mode
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
### Git Integration Troubleshooting
|
||||
|
||||
**Problem: `.gitignore` ignores entire `.beads/` directory**
|
||||
|
||||
**Symptom**: JSONL file not tracked in git, can't commit beads
|
||||
|
||||
**Cause**: Incorrect `.gitignore` pattern blocks everything
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Check .gitignore
|
||||
cat .gitignore | grep beads
|
||||
|
||||
# ❌ WRONG (ignores everything including JSONL):
|
||||
.beads/
|
||||
|
||||
# ✅ CORRECT (ignores only SQLite cache):
|
||||
.beads/*.db
|
||||
.beads/*.db-*
|
||||
```
|
||||
|
||||
**After fixing**: Remove the `.beads/` line and add the specific patterns. Then `git add .beads/issues.jsonl`.
|
||||
|
||||
---
|
||||
|
||||
### Permission Troubleshooting
|
||||
|
||||
**Problem: bd commands prompt for permission despite whitelist**
|
||||
|
||||
**Symptom**: `bd` commands ask for confirmation even with `Bash(bd:*)` in settings.local.json
|
||||
|
||||
**Root Cause**: Wildcard patterns in settings.local.json don't actually work - not for bd, not for git, not for any Bash commands. This is a general Claude Code limitation, not bd-specific.
|
||||
|
||||
**How It Actually Works**:
|
||||
- Individual command approvals (like `Bash(bd ready)`) DO persist across sessions
|
||||
- These are stored server-side by Claude Code, not in local config files
|
||||
- Commands like `git status` work without prompting because they've been individually approved many times, creating the illusion of a working wildcard pattern
|
||||
|
||||
**Permanent Solution**:
|
||||
1. Trigger each bd subcommand you use frequently (see command list below)
|
||||
2. When prompted, click "Yes, and don't ask again" (NOT "Allow this time")
|
||||
3. That specific command will be permanently approved across all future sessions
|
||||
|
||||
**Common bd Commands to Approve**:
|
||||
```bash
|
||||
bd ready
|
||||
bd list
|
||||
bd stats
|
||||
bd blocked
|
||||
bd export
|
||||
bd version
|
||||
bd quickstart
|
||||
bd dep cycles
|
||||
bd --help
|
||||
bd [command] --help # For any subcommand help
|
||||
# bd-42 Fix authentication bug [P1, bug, in_progress]
|
||||
# bd-43 Add user settings page [P2, feature, open]
|
||||
```
|
||||
|
||||
**Note**: Dynamic commands with arguments (like `bd show <issue-id>`, `bd create "title"`) must be approved per-use since arguments vary. Only static commands can be permanently whitelisted.
|
||||
## Common Patterns for AI Agents
|
||||
|
||||
---
|
||||
### Claim and Complete Work
|
||||
|
||||
## Tips
|
||||
|
||||
**Use JSON for parsing**:
|
||||
```bash
|
||||
bd ready --json | jq '.[0].id'
|
||||
# 1. Find available work
|
||||
bd ready --json
|
||||
|
||||
# 2. Claim issue
|
||||
bd update bd-42 --status in_progress --json
|
||||
|
||||
# 3. Work on it...
|
||||
|
||||
# 4. Close when done
|
||||
bd close bd-42 --reason "Implemented and tested" --json
|
||||
```
|
||||
|
||||
**Bulk operations**:
|
||||
### Discover and Link Work
|
||||
|
||||
```bash
|
||||
bd close issue-1 issue-2 issue-3 --reason "Sprint complete"
|
||||
# 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
|
||||
```
|
||||
|
||||
**Quick filtering**:
|
||||
### Batch Operations
|
||||
|
||||
```bash
|
||||
bd list --status open --priority 0 --type bug
|
||||
# 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
|
||||
```
|
||||
|
||||
**Built-in help**:
|
||||
### Session Workflow
|
||||
|
||||
```bash
|
||||
bd quickstart # Comprehensive guide
|
||||
bd create --help # Command-specific help
|
||||
# Start of session
|
||||
bd ready --json # Find work
|
||||
|
||||
# During session
|
||||
bd create "..." -p 1 --json
|
||||
bd update bd-42 --status in_progress --json
|
||||
# ... work ...
|
||||
|
||||
# End of session (IMPORTANT!)
|
||||
bd sync # Force immediate sync, bypass debounce
|
||||
```
|
||||
|
||||
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
|
||||
|
||||
## See Also
|
||||
|
||||
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
|
||||
- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
|
||||
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
|
||||
- [LABELS.md](../LABELS.md) - Label system guide
|
||||
- [README.md](../README.md) - User documentation
|
||||
|
||||
Reference in New Issue
Block a user