# install > Install BMAD+ agents, skills, instruction files and configuration into a project: every flag, what is written, how a re-run behaves, real output and the errors you can meet. Canonical: https://bmad-plus.rochetta.fr/docs/reference/cli-install/ 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/) › 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 **In your project terminal** ```sh npx bmad-plus install [-d ] [-p ] [-y] [-l ] [--tools ] [--mode ] [--provision-python] ``` **Options of install** | Flag | Argument | Default | What it does | | --- | --- | --- | --- | | `-d, --directory ` | folder | current folder | Project to install into. | | `-p, --packs ` | comma list | asked interactively | Pack ids: `core`, `osint`, `maker`, `shield`, `seo`, `memory`, `dev-studio`, `backup`, `animated`, `design`, or `all` (every pack), or `none`. Core is always installed. An unknown id is an error. | | `-y, --yes` | - | off | Accept every default and skip all prompts. Required when there is no terminal. | | `-l, --lang ` | language code | asked, or `en` with `--yes` | Language of the installer screens: `en`, `fr`, `es`, `de`, `pt-br`, `ru`, `zh`, `he`, `ja`, `it`. | | `--tools ` | comma list | auto-detect | Which assistants to write instruction files for: ids (`claude-code`, `gemini-cli`, `antigravity`, `cursor`, `codex-cli`, `opencode`, `aider`), `all`, or `none` / `skip` to leave tool configuration untouched. | | `--mode ` | `manual`, `autopilot`, `hybrid` | existing value, else `manual` | Execution mode written to `_bmad/config.yaml`. An explicit value replaces the existing one. | | `--provision-python` | - | off | Create an isolated Python environment under `.bmad/venv//` for packs that need one (today: SEO). Never runs unless asked. | ## 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. **Language** The installer language (see the CLI overview). Skipped when `--lang` is given. 2. **Packs** A multi-select of the optional packs. Skipped when `--packs` is given. 3. **Tools** Asked only when no AI tool was detected in the folder and `--tools` is not given. 4. **Name** Your first name; agents use it to greet you. Defaults to the existing configuration, then your system user name. 5. **Communication language** The language agents answer in. Written to the configuration. 6. **Test environment** The URL of a test environment for human acceptance recipes; leave it blank if you have none. 7. **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. **Files and folders written by install** | Path | What it is | | --- | --- | | `.agents/skills/` | Agents, skills and pack folders of the selected packs. | | `.agents/data/` | Shared data, notably `role-triggers.yaml` (automatic role activation). | | `_bmad/module.yaml`, `_bmad/module-help.csv` | Module description and help index. | | `_bmad/config.yaml` | Your project configuration. Created, or merged with existing keys kept. | | `_bmad/.bmad-plus-install.json` | The manifest: version, packs, tools, adapter hashes, ownership inventory, mode, user and language. | | `AGENTS.md` and tool files | Instruction files for the selected tools (see the adapters page). Not written with `--tools none`. | | `_bmad-output/discovery/`, `_bmad-output/build/`, `docs/` | Empty output folders agents write into. | | `.agents/memory/`, `~/.bmad-plus/brain` | With the Memory pack: project memory files and, if needed, a global brain. A failure here is a warning, not an error. | | `.bmad/venv//` | Only with `--provision-python`. | | `.bmad/update.lock` | Held while the command runs, then removed. | > **Note · Your .gitignore is yours** The installer does not edit `.gitignore`. Whether the installed folders show up in `git status` depends on your own ignore rules. In the recorded acceptance run the demo project already ignored them, so `git status --short` stayed empty. ## 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 (`: 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 `.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 `.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 **Exit codes of install** | Code | Meaning | | --- | --- | | 0 | Installed, or nothing left to add. | | 1 | No terminal and no `--yes`; version conflict; unknown pack, tool or mode; a pack that cannot be listed; a lock held by another install or update; a cancelled prompt. | ## 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). **Unattended install, Core + Design, Claude Code** ```text $ 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 🚀 ``` Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 1; npm notice lines removed; the quick-start box is abridged (workflow and output-folder lines omitted)) ## Errors and what to do **Messages of install** | Message | Cause | What to do | | --- | --- | --- | | `This command requires a terminal. Run ...` | Input is not a terminal (script, CI, pipe) and `--yes` is missing. | Add `--yes` and, if you want adapters, `--tools `. | | `BMAD+: Unknown pack ID(s): x. Available: core, osint, maker, shield, seo, memory, dev-studio, backup, animated, design, all.` | A pack id in `--packs` is misspelled. | Use one of the listed ids. | | `BMAD+: Unknown tool ID(s): x. Available: claude-code, gemini-cli, antigravity, cursor, codex-cli, opencode, aider, all, none.` | A tool id in `--tools` is misspelled. | Use one of the listed ids. | | `BMAD+: Unknown execution mode: x` | `--mode` is not `manual`, `autopilot` or `hybrid`. | Pick one of the three. | | `BMAD+ v0.22.0 is installed; this package is v0.23.0. Run `bmad-plus update` first ...` | The project holds another version than the package you run. | Run `update`, then re-run `install` to add packs or tools. | | `Downgrade refused: BMAD+ vX is installed and this package is vY.` | The package you run is older than the installation. | Run a newer package: `npx bmad-plus@latest install`. | | `Another update is in progress: .` | Another install or update holds `.bmad/update.lock`. | Wait for it. If it was interrupted, `doctor` tells you when the lock is stale and which file to delete. | | `: existing project instructions preserved.` | You already have that instruction file and it is not BMAD+’s (interactive install), or you edited the BMAD+ file. | Nothing breaks: the spine `AGENTS.md` holds the shared instructions. Merge by hand, or move your file aside and re-run. Note that `--yes` would have saved your file as `.bak` and replaced it. | | `External module design-skill is X but this BMAD+ expects exactly Y; reinstall bmad-plus so its pinned dependency matches.` | The Design pack’s external skills do not match the version this release pins. | Reinstall the package (`npm install` or `npx bmad-plus@`). The project was not touched. | | `Installation changed while preparing install. Please retry.` | Another process changed the manifest during preflight. | Run the command again. | | `_bmad/config.yaml could not be parsed; it was left unchanged.` | The file is not valid YAML. | Fix the file, then re-run to merge defaults. | | `Memory/brain initialization failed (non-fatal, install continues): ...` | The home folder is read-only or missing (container, CI). | Safe to ignore; set `BMAD_PLUS_BRAIN` to a writable folder if you want the global brain. | ## Examples **Interactive, the usual way** ```sh npx bmad-plus@0.23.0 install ``` **Unattended, two packs, one assistant** ```sh npx bmad-plus install --packs core,design --tools claude-code --yes --lang fr ``` **Everything, every assistant** ```sh npx bmad-plus install --packs all --tools all --yes ``` **Agents and skills only, no instruction file touched** ```sh npx bmad-plus install --tools none --yes ``` **SEO pack with its Python environment** ```sh npx bmad-plus install --packs seo --provision-python ``` **See also** - [CLI overview](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/) - [Check the result with doctor](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/) - [Move to a newer version](https://bmad-plus.rochetta.fr/docs/reference/cli-update/) - [Adapters and tool ids](https://bmad-plus.rochetta.fr/docs/reference/adapters/) - [The configuration written](https://bmad-plus.rochetta.fr/docs/reference/config-yaml/) - [The whole lifecycle](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/) - [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)