--- id: doctor title: bd doctor slug: /cli-reference/doctor sidebar_position: 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) ```