# Install, update, uninstall

> The whole life of BMAD+ in a project: install, check, update with a policy and receipts, restore, uninstall while keeping your memory. What each step writes and removes, and how it behaves offline.

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

BMAD+ documentation › [Guides](https://bmad-plus.rochetta.fr/docs/guides/) › Install, update, uninstall

BMAD+ lives inside your project, next to your code. That raises three fair questions: how do I install it without it taking over, how do I keep it current without losing my own edits, and how do I remove it without losing my work. This page follows one installation from the first command to the last and says, for each step, what is read, what is written and what is removed. The principle is the same everywhere: BMAD+ keeps a list of the files it owns, with a fingerprint of each, and acts only on files that still match.

<a id="video-install-and-keep-memory"></a>
Video: [Install, update, uninstall, and keep your memory](https://bmad-plus.rochetta.fr/media/install-and-keep-memory-en.mp4) — One install command, a health check with doctor, updates that keep your edits, and an uninstall that leaves memory and configuration in place.
[Captions (WebVTT)](https://bmad-plus.rochetta.fr/media/install-and-keep-memory-en.vtt)

Transcript:

> Run one command from your project folder, and choose your adapters and packs. The installer writes the agent instructions, the shared project spine and the adapters you selected. Then doctor checks the installation and reports how many checks passed. Updates keep the files you customised: BMAD+ tracks which files it manages. A version check only looks. Automatic updates need an explicit project policy. Uninstall removes only files that still match what was installed. Your memory, your edits and your configuration stay where they are. It never deletes a folder recursively, so hidden files and nested content survive.

Described transcript:

- **0:00** On screen: A faint beam of light falls through dark haze onto a point on a dark surface. Where it lands, thin amber lines burst outward in every direction and branch like circuit traces. The caption reads “npx bmad-plus@0.23.0 install”. Narration: Run one command from your project folder, and choose your adapters and packs.
- **0:06** On screen: A terminal window titled “~/app”. The command npx bmad-plus install --lang en is typed. The installer asks “Which packs to install? (Core is always included)” and lists the nine optional packs; Shield is chosen (“Selected packs: Core, Shield”). Then “Which IDE are you using?” lists seven tools — Claude Code, Gemini CLI, Antigravity, Cursor, Codex CLI, OpenCode and Aider — and Claude Code is chosen. More lines follow: “Detected IDEs: Claude Code”, a first-name prompt (Developer), the communication language (English), a prompt for a test environment URL and the execution mode (“Manual — You call agents yourself”). The view zooms in on two green checks: “5 agents, 6 skills, 4 files copied”, with “files copied” outlined in orange, and “1 IDE(s) configured”. Narration: The installer writes the agent instructions, the shared project spine and the adapters you selected.
- **0:17** On screen: A terminal. The command bmad-plus doctor is typed. The screen shows “BMAD+ Doctor v0.23.0” and “Manifest found: v0.23.0”, then a “BMAD+ Health Report” whose first line, “87/87 checks passed”, is outlined in orange. Below it: “0 error(s), 0 warning(s)”, “Installed: v0.23.0 | Executing CLI: v0.23.0” and “Ownership inventory: complete”. The screen ends on a note that the published version is not checked here (the command bmad-plus update-check --json checks npm), and “Installation checks passed.” in green. Narration: Then doctor checks the installation and reports how many checks passed.
- **0:23** On screen: A terminal. First a managed file is edited: echo '# my notes' >> .agents/skills/agent-strategist/SKILL.md. Then bmad-plus update-check prints “Installed: 0.22.0; running: 0.23.0; channel latest: 0.23.0” and “update-available: approval-required”, with “update-available” outlined. bmad-plus update --yes follows: “BMAD+ Updater v0.23.0”, “Installed: v0.22.0 → Executing package: v0.23.0” and “Planned changes: 12 files (0 no longer shipped, removed with backup); preserved conflicts: 1.” The view zooms in, and “SKILL.md: preserved” is outlined in the line “.agents/skills/agent-strategist/SKILL.md: preserved (modified-managed-file).” The run ends with “12 files updated; 1 local conflicts preserved.”, the path of a receipt under .bmad/updates, and “BMAD+ v0.23.0 applied partially. Reload your agent instructions or start a new session.” Narration: Updates keep the files you customised: BMAD+ tracks which files it manages. A version check only looks. Automatic updates need an explicit project policy.
- **0:38** On screen: A terminal. The root file is edited: echo '# my notes' >> AGENTS.md. A memory file is written: mkdir -p .agents/memory && echo 'decision: keep it simple' > .agents/memory/decisions.md. Then bmad-plus uninstall --yes prints “BMAD+ Uninstaller”, “BMAD+ v0.23.0 (installed 2026-10-18)”, “Selected packs: core, design” and “BMAD+ removed (105 items)”, outlined. The next line reads “Project memory, settings, and unknown or modified files have been preserved”, with “have been preserved” outlined. Last, the command ls AGENTS.md .agents/memory _bmad lists AGENTS.md, then decisions.md under .agents/memory, then config.yaml under _bmad. The name config.yaml is outlined. Narration: Uninstall removes only files that still match what was installed. Your memory, your edits and your configuration stay where they are.
- **0:52** On screen: A tall stack of thin translucent slabs stands in the dark. A warm light grows inside it, brightens, and the slabs open out around a bright flare. The caption reads “Nothing deleted recursively”. Narration: It never deletes a folder recursively, so hidden files and nested content survive.
- **0:59** On screen: A dim blue-black sky with a faint band of light at the horizon. The address “bmad-plus.rochetta.fr” fades in, in orange, and fades out.

<a id="the-path"></a>
## The path in six steps

1. **Install** Copies agents, skills and instruction files, writes the configuration and the manifest.

   ```sh
   npx bmad-plus install
   ```
2. **Check** A read-only health report: are all the files there and unchanged?

   ```sh
   npx --no-install bmad-plus doctor
   ```
3. **Look for news** Ask npm whether a newer release exists, without applying it.

   ```sh
   npx --no-install bmad-plus update-check
   ```
4. **Decide the policy** Keep the default (tell me, I decide), switch lookups off, or allow automatic updates inside a version range.

   ```sh
   npx --no-install bmad-plus update-policy --mode notify
   ```
5. **Update** Plan, back up, write, verify, leave a receipt. Undo with `--restore`.

   ```sh
   npx --no-install bmad-plus update --latest --yes
   ```
6. **Uninstall** Remove only what BMAD+ owns; memory, settings and your edits stay.

   ```sh
   npx --no-install bmad-plus uninstall --yes
   ```

> **Warning · Steps 2 to 6 need a local copy** The installer does not put `bmad-plus` in your project’s `node_modules`, so `npx --no-install bmad-plus ...` fails right after step 1 (`npx canceled due to missing packages and no YES option`). Add the package once with `npm install --save-dev bmad-plus`, or run those steps as `npx bmad-plus ...`, which downloads it when needed. The generated `CLAUDE.md` and `AGENTS.md` ask the assistant to run `npx --no-install bmad-plus update-check`; without a local copy the command is unavailable and the assistant skips the update check and carries on with your task. See the [CLI overview](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/).

<a id="ownership"></a>
## How BMAD+ knows what is its own

Everything rests on one file written by `install`: `_bmad/.bmad-plus-install.json`, the manifest. It records the version, the packs, the tools, your name and language, the execution mode, an `adapterHashes` map (one fingerprint per instruction file) and a `fileInventory`: for every agent, skill and data file BMAD+ placed, its SHA-256 fingerprint. Line endings are normalised before fingerprinting instruction files, so a Windows checkout does not look like an edit.

**Ownership inventory states shown by doctor**

| State | Meaning | Consequence |
| --- | --- | --- |
| `complete` | Every shipped file is recorded. | Updates can be automatic when the policy allows. |
| `incomplete` | Some file was already there, with different content, at install time. | Those files are treated as yours. |
| `legacy` | Installed before ownership hashes existed. | Updates back up the original pack files first; `--auto` refuses. |
| `invalid` | The inventory is malformed. | `doctor` reports an error; repair the manifest or reinstall. |

<a id="each-step"></a>
## What each step reads, writes and removes

**Effects of each lifecycle command**

| Command | Reads | Writes | Removes |
| --- | --- | --- | --- |
| `install` | Existing manifest and configuration. | Agents, skills, data, module files, `AGENTS.md` and tool files, `_bmad/config.yaml`, the manifest, empty output folders. | Nothing. |
| `doctor` | Manifest, files, hashes, lock. | Nothing. | Nothing. |
| `update-check` | Manifest, policy; npm unless offline or off. | `.bmad/update-check.json` (cache). | Nothing. |
| `update-policy` | Policy file. | `_bmad/update-policy.json`, only when you pass options. | Nothing. |
| `update` | Manifest, files, hashes, policy. | Changed files, manifest, `.bmad/updates/<id>/` (receipt, backups), the lock. | Files the new version no longer ships (unchanged ones, with a backup). |
| `update --restore` | Receipt and backups. | The saved files, the receipt status. | Files the update had added. |
| `uninstall` | Manifest, files. | Nothing. | Owned and unchanged files, the manifest, then empty folders. |

<a id="your-edits"></a>
## When you have edited files

**How each command treats a file you changed**

| Situation | `install` | `update` | `uninstall` |
| --- | --- | --- | --- |
| A managed agent or skill file you edited | Kept, warning. | Kept, listed as a conflict. | Kept. |
| An instruction file BMAD+ wrote and you then edited | Kept. | Kept, listed as a conflict. | Kept. |
| An instruction file you wrote yourself, never BMAD+’s | Kept when interactive; with `--yes`, saved as `<file>.bak` then replaced. | Kept, listed as a conflict. | Kept (no marker). |
| A file you added in a BMAD+ folder | Untouched. | Untouched. | Kept, and its folder. |
| `_bmad/config.yaml` | Merged, your keys win. | Untouched. | Kept. |

<a id="offline"></a>
## Working offline

- Once the package is installed locally (add it once with `npm install --save-dev bmad-plus`, then use `npx --no-install bmad-plus ...`), `install`, `doctor`, `update-policy`, `uninstall` and a plain `update` run with no network at all.
- `update-check` and `update --latest` are the only commands that ask npm. With no connection, `update-check` reports status `unknown` (reason `registry-unavailable`, or `offline` with `--offline`), exits 0, and an assistant simply carries on with your task.
- A stale cached answer is shown as such, with `stale: true`; it is never presented as current.
- Only the very first `npx bmad-plus install` needs the network, to fetch the package, unless you installed it from a file.

<a id="recovery"></a>
## When something goes wrong

- A failed update rolls itself back and prints the exact `update --restore <id>` command. Receipts stay under `.bmad/updates/`.
- A project lock (`.bmad/update.lock`) older than 60 minutes, or whose process is gone, is reported by `doctor` as stale with the file to delete. A lock whose process is provably dead on this machine is taken over by the next install or update.
- A damaged manifest is copied to `_bmad/.bmad-plus-install.json.corrupt.bak` before `install` replaces it.
- An installation from before ownership hashes existed (0.12.2 or earlier) is migrated once by running an explicit newer package: `npx --yes bmad-plus@0.13.0 update --yes`. The originals are backed up first.
- A downgrade is always refused. To go back, use `update --restore` with the receipt of the update you want to undo.

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

<a id="example-install-lifecycle-customised-project"></a>
### Update a project where you edited instruction files

You added your own rules to `CLAUDE.md` and tweaked one agent file, and you want the newest BMAD+ without losing either.

**In your AI assistant**

```text
Check whether a newer BMAD+ exists for this project. If so, update it, and list exactly which files were kept because I edited them and why.
```

**What you should get** The assistant runs `update-check`, then `update --latest --yes` with your approval. The command prints a plan such as `Planned changes: N files (R no longer shipped, removed with backup); preserved conflicts: 2.` and one line per conflict: `CLAUDE.md: preserved (local-instructions).` and `<agent file>: preserved (modified-managed-file).` Those two files are untouched; everything else is updated after a backup, and the receipt path under `.bmad/updates/` is reported so the update can be undone with `update --restore`.

**See also**

- [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)
- [update-check](https://bmad-plus.rochetta.fr/docs/reference/cli-update-check/)
- [update-policy](https://bmad-plus.rochetta.fr/docs/reference/cli-update-policy/)
- [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/)
- [uninstall](https://bmad-plus.rochetta.fr/docs/reference/cli-uninstall/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)
- [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/)

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

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