* docs: generate CLI reference from live help * docs(cli): move bd version stamp from per-command pages to index only Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on every per-command CLI reference page (writeSingleCommandDoc) and the docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now lives only on the index page emitted by scripts/generate-cli-docs.sh: - Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md): labelled "Latest" - Versioned snapshots (website/versioned_docs/version-X.Y.Z/...): labelled with the explicit semver tag parsed from the directory name This eliminates the 100+-file no-signal diff a release version bump otherwise produces, restoring the "regen as a separate small commit" workflow PR #3704 enables. After this change a version bump alone yields zero diff on the dev tree; only the new versioned snapshot created at release-cut time carries the new tag. No datestamps are introduced anywhere — scripts/generate-cli-docs.sh --check remains deterministic across CI runs. Refs: mybd-afb, PR #3704 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: CI Bot <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
153 lines
7.8 KiB
Markdown
153 lines
7.8 KiB
Markdown
---
|
|
id: doctor
|
|
title: bd doctor
|
|
slug: /cli-reference/doctor
|
|
sidebar_position: 600
|
|
---
|
|
|
|
<!-- AUTO-GENERATED: do not edit manually -->
|
|
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 JSONL (source of truth)
|
|
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)
|
|
```
|