install

install is the command that puts BMAD+ into a project. It copies the agents and skills of the packs you choose, writes the instruction files your AI assistants read, creates the configuration, and records a manifest of everything it owns so that update, doctor and uninstall can later act safely. Run it once per project, and again whenever you want to add a pack or a tool.

Synopsis#

npx bmad-plus install [-d <path>] [-p <packs>] [-y] [-l <code>] [--tools <tools>] [--mode <mode>] [--provision-python]

The interactive wizard#

Without --yes, the installer asks the questions below, in this order. The language, pack and tool questions are skipped when you gave --lang, --packs or --tools; the name, communication language, test environment and execution mode are always asked. Core is always included in the pack list, and packs already installed are pre-selected.

1. 01

   Language

   The installer language (see the CLI overview). Skipped when --lang is given.

2. 02

   Packs

   A multi-select of the optional packs. Skipped when --packs is given.

3. 03

   Tools

   Asked only when no AI tool was detected in the folder and --tools is not given.

4. 04

   Name

   Your first name; agents use it to greet you. Defaults to the existing configuration, then your system user name.

5. 05

   Communication language

   The language agents answer in. Written to the configuration.

6. 06

   Test environment

   The URL of a test environment for human acceptance recipes; leave it blank if you have none.

7. 07

   Execution mode

   manual (you call the agents), autopilot (Nexus runs the pipeline) or hybrid (autopilot with frequent checkpoints). Always asked. A --mode value wins over your answer.

With --yes, nothing is asked: the name comes from the existing configuration or your system user name, the communication language from the existing configuration, --lang or your system locale, and the mode from --mode, the existing configuration or manual. An unattended install never replaces a setting that already exists.

What it reads and writes#

The command first lists every file of every selected pack. If one cannot be listed (for example the Design pack’s external skills do not match the pinned version), it stops before writing anything. It then takes a project lock, writes files atomically, and finishes with the manifest. It opens no network connection itself; the only exception is --provision-python, which asks a Python installer (uv, with pipx or pip as fallbacks) to fetch the pack’s requirements.

Running it again#

• Same version: only missing packs, tools and files are added. Packs and tools the installation already owns are kept and refreshed.
• Files you changed, or files that are not recorded as BMAD+’s, are preserved with a warning (<file>: locally changed or unowned content preserved.).
• Your own instruction files (CLAUDE.md, GEMINI.md and so on): an interactive install preserves them and warns; with --yes they are first copied to <file>.bak (numbered if needed) and then replaced by the BMAD+ file. A BMAD+ file that you edited is always preserved. Older BMAD+ files without ownership hashes are saved as <file>.bak first.
• _bmad/config.yaml is merged: existing keys win, missing defaults are added, and answers you gave explicitly in the wizard (or --mode) replace the old value. If the file cannot be parsed it is left untouched, with a warning.
• A different version is refused. Use update: it plans the change, backs up files and records a receipt.
• A manifest that cannot be read is first copied to _bmad/.bmad-plus-install.json.corrupt.bak (numbered if it exists), then replaced.

Exit codes#

Real output#

This is the recorded install of the Core and Design packs for Claude Code, in French (--lang fr), from the human acceptance run of 0.23.0. The line “5 agents, 9 skills, 4 files copied” counts agent folders, skill folders and other files copied. The panel ends with the quick-start guide; its example lines depend on the packs you chose (here the Design line).

$ npx bmad-plus install --yes --lang fr --packs core,design --tools claude-code --directory .\demo-app
T   BMAD+ Installer v0.23.0
|
•  ✨ Created by Laurent Rochetta — github.com/lrochetta/BMAD-PLUS
|
•  Installation dans: C:\Users\you\demo-app
|
*  Packs sélectionnés: ⚙️ Core, 🎨 Design
|
•  IDE détectés: Claude Code
|
o  ✅ 5 agents, 9 skills, 4 fichiers copiés
|
o  ✅ 1 IDE configuré(s)
|
o  ✅ Installation terminée — Comment commencer -------------------------------+
|                                                                              |
|  💬 À qui parler ?                                                           |
|                                                                              |
|    Discuter d'une idée          →  "Atlas, [...]"                            |
|    Créer un PRD                 →  "Atlas, create PRD"                       |
|    Architecture technique       →  "Forge, propose architecture"             |
|    Implémenter du code          →  "Forge, implement story [X]"              |
|    Tester / code review         →  "Sentinel, review module [X]"             |
|    Planifier un sprint          →  "Nexus, create epics"                     |
|    Tout automatiser             →  "autopilot"                               |
|    Design avec Atelier          →  "/design read"                            |
|                                                                              |
|  📦 Commandes CLI:                                                           |
|    npx bmad-plus install    — Installer agents & skills                      |
|    npx bmad-plus update     — Mettre à jour (conserve la config)             |
|    npx bmad-plus doctor     — Vérifier l'installation                        |
|    npx bmad-plus uninstall  — Supprimer BMAD+ du projet                      |
|                                                                              |
|  💡 Exemples rapides:                                                        |
|    🎨 Design : "/design read" → Atelier vous interroge, puis construit       |
|                                                                              |
+------------------------------------------------------------------------------+
|
—  BMAD+ est prêt ! Parle à Atlas pour commencer 🚀

Errors and what to do#

Examples#

npx bmad-plus@0.23.0 install

npx bmad-plus install --packs core,design --tools claude-code --yes --lang fr

npx bmad-plus install --packs all --tools all --yes

npx bmad-plus install --tools none --yes

npx bmad-plus install --packs seo --provision-python