* fix(init): wire git origin as Dolt remote Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync. Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only. _codex-gpt-5-xhigh on behalf of maphew_ * test: keep embedded command stderr out of parsed stdout Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_ --------- Co-authored-by: CI Bot <ci@beads.test>
7.8 KiB
| id | title | slug | sidebar_position |
|---|---|---|---|
| doctor | bd doctor | /cli-reference/doctor | 600 |
Generated from bd help --doc doctor
bd doctor
Sanity check the beads installation for the current directory or specified path.
This command checks:
- If .beads/ directory exists
- Database version and migration status
- Schema compatibility (all required tables and columns present)
- Whether using hash-based vs sequential IDs
- If CLI version is current (checks GitHub releases)
- If Claude plugin is current (when running in Claude Code)
- File permissions
- Circular dependencies
- Git hooks (pre-commit, post-merge, pre-push)
- .beads/.gitignore up to date
- Metadata.json version tracking (LastBdVersion field)
Performance Mode (--perf): Run performance diagnostics on your database:
- Times key operations (bd ready, bd list, bd show, etc.)
- Collects system info (OS, arch, SQLite version, database stats)
- Generates CPU profile for analysis
- Outputs shareable report for bug reports
Export Mode (--output): Save diagnostics to a JSON file for historical analysis and bug reporting. Includes timestamp and platform info for tracking intermittent issues.
Specific Check Mode (--check): Run a specific check in detail. Available checks:
- artifacts: Detect and optionally clean beads classic artifacts (stale JSONL, SQLite files, cruft .beads dirs). Use with --clean.
- conventions: Check for convention drift (lint warnings, stale issues, orphaned issues). Advisory only - warns, never blocks.
- pollution: Detect and optionally clean test issues from database
- validate: Run focused data-integrity checks (duplicates, orphaned deps, test pollution, git conflicts). Use with --fix to auto-repair.
Deep Validation Mode (--deep): Validate full graph integrity. May be slow on large databases. Additional checks:
- Parent consistency: All parent-child deps point to existing issues
- Dependency integrity: All deps reference valid issues
- Epic completeness: Find epics ready to close (all children closed)
- Agent bead integrity: Agent beads have valid state values
- Mail thread integrity: Thread IDs reference existing issues
- Molecule integrity: Molecules have valid parent-child structures
Server Mode (--server): Run health checks for Dolt server mode connections (bd-dolt.2.3):
- Server reachable: Can connect to configured host:port?
- Dolt version: Is it a Dolt server (not vanilla MySQL)?
- Database exists: Does the 'beads' database exist?
- Schema compatible: Can query beads tables?
- Connection pool: Pool health metrics
Migration Validation Mode (--migration): Run Dolt migration validation checks with machine-parseable output. Use --migration=pre before migration to verify readiness:
- JSONL file exists and is valid (parseable, no corruption)
- All JSONL issues are present in SQLite (or explains discrepancies)
- No blocking issues prevent migration Use --migration=post after migration to verify completion:
- Dolt database exists and is healthy
- All issues from JSONL are present in Dolt
- No data was lost during migration
- Dolt database has no locks or uncommitted changes Combine with --json for machine-parseable output for automation.
Agent Mode (--agent): Output diagnostics designed for AI agent consumption. Instead of terse pass/fail messages, each issue includes:
- Observed state: what the system actually looks like
- Expected state: what it should look like
- Explanation: full prose context about the issue and why it matters
- Commands: exact remediation commands to run
- Source files: where in the codebase to investigate further
- Severity: blocking (prevents operation), degraded (partial function), or advisory (informational only) ZFC-compliant: Go observes and reports, the agent decides and acts. Combine with --json for structured agent-facing output.
Suppressing Warnings: Suppress specific warnings by setting doctor.suppress.<check-slug> config: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: "Git Hooks" → "git-hooks". Only warnings are suppressed; errors and passing checks always show. To unsuppress: bd config unset doctor.suppress.<slug>
Examples: bd doctor # Check current directory bd doctor /path/to/repo # Check specific repository bd doctor --json # Machine-readable output bd doctor --agent # Agent-facing diagnostic output bd doctor --agent --json # Structured agent diagnostics (JSON) bd doctor --fix # Automatically fix issues (with confirmation) bd doctor --fix --yes # Automatically fix issues (no confirmation) bd doctor --fix -i # Confirm each fix individually bd doctor --fix --fix-child-parent # Also fix child→parent deps (opt-in) bd doctor --fix --force # Force repair even when database can't be opened bd doctor --fix --source=jsonl # Rebuild database from a JSONL export bd doctor --dry-run # Preview what --fix would do without making changes bd doctor --perf # Performance diagnostics bd doctor --output diagnostics.json # Export diagnostics to file bd doctor --check=artifacts # Show classic artifacts (JSONL, SQLite, cruft dirs) bd doctor --check=artifacts --clean # Delete safe-to-delete artifacts (with confirmation) bd doctor --check=conventions # Convention drift check (lint, stale, orphans) bd doctor --check=pollution # Show potential test issues bd doctor --check=pollution --clean # Delete test issues (with confirmation) bd doctor --check=validate # Data-integrity checks only bd doctor --check=validate --fix # Auto-fix data-integrity issues bd doctor --deep # Full graph integrity validation bd doctor --server # Dolt server mode health checks bd doctor --migration=pre # Validate readiness for Dolt migration bd doctor --migration=post # Validate Dolt migration completed bd doctor --migration=pre --json # Machine-parseable migration validation
bd doctor [path] [flags]
Flags:
--agent Agent-facing diagnostic mode: rich context for AI agents (ZFC-compliant)
--check string Run specific check in detail (e.g., 'pollution')
--check-health Quick health check for git hooks (silent on success)
--clean For pollution check: delete detected test issues
--deep Validate full graph integrity
--dry-run Preview fixes without making changes
--fix Automatically fix issues where possible
--fix-child-parent Remove child→parent dependencies (opt-in)
-i, --interactive Confirm each fix individually
--migration string Run Dolt migration validation: 'pre' (before migration) or 'post' (after migration)
--orchestrator Running in orchestrator multi-workspace mode (routes.jsonl is expected, higher duplicate tolerance)
--orchestrator-duplicates-threshold int Duplicate tolerance threshold for orchestrator mode (wisps are ephemeral) (default 1000)
-o, --output string Export diagnostics to JSON file
--perf Run performance diagnostics and generate CPU profile
--server Run Dolt server mode health checks (connectivity, version, schema)
-v, --verbose Show all checks (default shows only warnings/errors)
-y, --yes Skip confirmation prompt (for non-interactive use)