Browse the documentation

doctor

A read-only health report on an installation: manifest, ownership inventory, modified files, instruction files, runtimes. Flags, every check code, the JSON report, real output and exit codes.

On this page

Synopsis
Exit codes
Real output
What it checks
The JSON report
Examples

doctor answers one question: is this installation intact? It compares what is on disk with what the manifest says BMAD+ installed, checks the configuration and instruction files, looks at the runtimes the packs need, and prints what it found. It never writes to the project and never contacts npm; to learn whether a newer release exists, use update-check. Run it after an install, after an update, or when something behaves oddly.

Synopsis

In your project terminal

npx bmad-plus doctor [-d <path>] [-l <code>] [--json] [--verify-python]

Options of doctor
Flag	Argument	What it does
`-d, --directory <path>`	folder	Project to check (default: current folder).
`-l, --lang <code>`	language code	Accepted for consistency; the report is always in English.
`--json`	-	Print the whole report as JSON instead of the human summary.
`--verify-python`	-	Also run the installed Python interpreters to check their version and imports. Without it, doctor runs no interpreter. It still never provisions or repairs anything.

Exit codes

Exit codes of doctor
Code	Meaning
0	No check is an error. Warnings alone do not fail the command.
1	At least one check is an error (for instance a missing required file, an unknown pack, a stale lock, a Node.js version below the minimum).

Real output

Recorded right after the install shown on the install page (Core and Design, 0.23.0). The human report lists only what is not a plain pass, plus the manifest line, then a summary box. “87/87 checks passed” counts every check, including the passing ones that are not listed.

doctor after a clean install

$ npx bmad-plus doctor --directory .\demo-app
T   BMAD+ Doctor v0.23.0
|
*  Manifest found: v0.23.0
|
o  BMAD+ Health Report ---------------------------------------------------------------------------------+
|                                                                                                       |
|  87/87 checks passed                                                                                  |
|  0 error(s), 0 warning(s)                                                                             |
|  Installed: v0.23.0 | Executing CLI: v0.23.0                                                          |
|  Ownership inventory: complete                                                                        |
|  Integrations use host-managed execution; host capabilities were not probed.                          |
|  Optional Nexus process execution requires an explicit plan; executable availability was not probed.  |
|                                                                                                       |
+-------------------------------------------------------------------------------------------------------+
|
•  Published version is not checked here. Use `bmad-plus update-check --json` to check npm.
|
—  Installation checks passed.

Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 2; npm notice lines removed)

What it checks

Each check has a code, a status (pass, warning or error), a message and often a path. The codes below are the ones the command can emit.

Check codes
Code	Status	Meaning and what to do
`installation.missing`	error	No manifest: BMAD+ is not installed in this folder. Check the folder or install.
`manifest.unreadable`, `manifest.invalid`	error	The manifest cannot be read or lacks required fields. Restore it, or run `install` again.
`manifest.valid`	pass	Manifest found, with its version.
`lock.active`	warning	An install or update holds the lock right now (pid and start time shown). Wait.
`lock.stale`	error	A lock older than 60 minutes, unreadable for over a minute, or whose process is dead. If nothing runs, delete `.bmad/update.lock`.
`lock.unreadable`	warning	The lock could not be inspected.
`version.cli`	pass / warning	Installed and running versions match, or not. A mismatch is the cue to run `update`.
`pack.unknown`, `pack.core-missing`	error	The manifest lists a pack this package does not know, or lacks Core.
`studio.resources`	pass / error	With Dev Studio: its workflows and resources resolve (or why not).
`shield.ai-register`	pass / warning	With Shield: the AI processing register covers the AI integrations found. Never an error.
`file.unchanged`	pass	A managed file matches its recorded hash.
`file.modified`	warning	A managed file was changed locally. Review before updating; `update` will preserve it.
`file.unowned`	warning	A required file exists with no recorded hash.
`file.missing`, `file.unreadable`	error	A required file is absent or unreadable. Re-run `install` to restore it.
`inventory.complete`, `.incomplete`, `.legacy`, `.invalid`, `inventory.omissions`	pass / warning / error	State of the ownership inventory. `legacy` (no inventory) and `incomplete` limit what `update --auto` may do; `invalid` is an error.
`config.present`, `config.missing`, `config.unreadable`	pass / error	Is `_bmad/config.yaml` there?
`integrations.legacy`, `integrations.invalid`, `adapters.invalid`	warning / error	The recorded tool selection or adapter hashes are missing or invalid.
`adapter.unchanged`, `.adopted`, `.unowned`, `.modified`, `.missing`, `.unreadable`	pass / warning / error	State of `AGENTS.md` and each selected tool file: untouched; replaced by a repository-generated file; not recognised as BMAD+’s; edited by you; absent; unreadable.
`runtime.node`	pass / error	Node.js is at least the minimum (20.0.0).
`runtime.requirements`	pass / error	For Python packs: the requirements file ships in the package.
`runtime.python-unverified`, `runtime.python-probe`	warning / pass	Python environment state; with `--verify-python`, the interpreter version and imports were actually run.
`package.unreadable`	error	The executing package cannot be inspected.

The JSON report

With --json the output is a single JSON document and nothing else. Its top-level keys are schemaVersion, projectDir, status (ok, warning or error), versions (installed, cli, and published, always null because doctor never queries npm), inventory (status, trackedFiles), packs, integrations, processExecution, runtimes, checks (the full list, passes included) and summary (passed, warnings, errors). The exit code follows summary.errors.

Note What doctor does not know

It does not probe your assistant: “Integrations use host-managed execution; host capabilities were not probed.” A green report means the files are intact, not that your AI tool has loaded them.

Examples

Gate a CI job on the result

npx bmad-plus doctor --json > doctor.json || echo "installation needs attention"

Check Python imports too

npx bmad-plus doctor --verify-python

doctor

Synopsis#

Exit codes#

Real output#

What it checks#

The JSON report#

Examples#