# 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.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › doctor

`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.

<a id="synopsis"></a>
## Synopsis

**In your project terminal**

```sh
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. |

<a id="exit-codes"></a>
## 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). |

<a id="real-output"></a>
## 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**

```text
$ 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)

<a id="checks"></a>
## 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. |

<a id="json-report"></a>
## 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.

<a id="examples"></a>
## Examples

**Gate a CI job on the result**

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

**Check Python imports too**

```sh
npx bmad-plus doctor --verify-python
```

**See also**

- [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/)
- [update-check](https://bmad-plus.rochetta.fr/docs/reference/cli-update-check/)
- [Adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/)
- [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Reference](https://bmad-plus.rochetta.fr/docs/reference/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)