# CLI overview

> How to run bmad-plus, the options every command shares, the installer languages, non-interactive use with --yes, and the exit codes you can rely on in scripts and CI.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/cli-overview/
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/) › CLI overview

Most of BMAD+ happens in a conversation with your assistant. The `bmad-plus` command is the part that runs in a terminal: it installs the agents into a project, keeps them up to date, checks the installation, and gives the agents a few deterministic helpers (questionnaires, swarms, durable task runs, acceptance recipes, review evidence). This page is for anyone who types a command, whether by hand, in a script or in CI.

<a id="invocation"></a>
## Running the command

The package is published on npm as `bmad-plus` and needs Node.js 20 or newer. You run it through `npx`, which is part of npm. Three forms matter.

**Ways to invoke bmad-plus**

| Form | What it does | Use it for |
| --- | --- | --- |
| `npx bmad-plus <command>` | Runs the copy found in the project; if there is none, npx downloads the published package first. | The first install in a project. |
| `npx bmad-plus@0.23.0 install` | Runs exactly that published version. | Reproducible installs. |
| `npx --no-install bmad-plus <command>` | Runs only a copy that is already installed locally and never downloads code; it fails when there is none. | Everything after the first install, once the package is also installed in the project (see the note below), and every command an agent runs on your behalf (for example `update-check`). |

> **Warning · --no-install needs a local copy** The installer does not add `bmad-plus` to your project’s `node_modules`, so right after `npx bmad-plus install` the `--no-install` form fails with `npx canceled due to missing packages and no YES option`. To use it, add the package once with `npm install --save-dev bmad-plus`; otherwise keep using `npx bmad-plus <command>`, which downloads the package when needed. The generated `CLAUDE.md` and `AGENTS.md` tell the assistant to run `npx --no-install bmad-plus update-check`; when that command is unavailable the assistant skips the update check and carries on with your task.

**Check which version runs**

```text
$ npx --no-install bmad-plus --version
0.23.0
```

Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 1)

> **Note · Chat words are not shell commands** `bmad-help`, `autopilot` and `parallel` are instructions you say to your assistant. Typing them in a terminal does nothing. Only the eighteen commands listed below exist in the shell.

<a id="commands"></a>
## The eighteen commands

**Which command for which job**

| Command | What it is for |
| --- | --- |
| `install` | Put the agents, skills, instruction files and configuration into a project. |
| `update` | Move an installed project to a newer version, with backups and a receipt you can restore from. |
| `uninstall` | Remove what BMAD+ owns and keep your memory, settings and edited files. |
| `doctor` | Read-only health report on the installation. |
| `update-check` | Ask npm whether a newer release exists, without applying it. |
| `update-policy` | Show or set the project policy that governs update checks and automatic updates. |
| `autoconfig` | Analyse an existing project, recommend packs, install them. |
| `scan` | Find your projects on disk and index them in the global brain. |
| `memory` | Health report and export of the persistent brain. |
| `mem` | Recall, write, reinforce and observe lessons in the memory journal. |
| `studio` | List Dev Studio workflows and prepare a read-only context bundle for one of them. |
| `intake` | Ask a pack’s questions a few at a time, record the answers, render the brief. |
| `swarm` | Deal, brief, check and tally a panel, jury or fanout of sub-agents. |
| `nexus` | Durable task runs with independent verification and acceptance. |
| `uat` (alias `recette`) | Human acceptance recipes: lint, build, serve, read, gate. |
| `review` | Seal the scope of a code review and compute an honest verdict. |
| `assurance` | Shield assurance cases with a hash-chained evidence ledger. |
| `ai-register` | Check the register of AI integrations in a project. |

**See also**

- [install](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [update](https://bmad-plus.rochetta.fr/docs/reference/cli-update/)
- [uninstall](https://bmad-plus.rochetta.fr/docs/reference/cli-uninstall/)
- [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/)
- [autoconfig](https://bmad-plus.rochetta.fr/docs/reference/cli-autoconfig/)
- [scan](https://bmad-plus.rochetta.fr/docs/reference/cli-scan/)
- [memory](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/)
- [mem](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/)
- [studio](https://bmad-plus.rochetta.fr/docs/reference/cli-studio/)
- [intake](https://bmad-plus.rochetta.fr/docs/reference/cli-intake/)
- [swarm](https://bmad-plus.rochetta.fr/docs/reference/cli-swarm/)
- [nexus](https://bmad-plus.rochetta.fr/docs/reference/cli-nexus/)
- [uat](https://bmad-plus.rochetta.fr/docs/reference/cli-uat/)
- [review](https://bmad-plus.rochetta.fr/docs/reference/cli-review/)
- [assurance](https://bmad-plus.rochetta.fr/docs/reference/cli-assurance/)
- [ai-register](https://bmad-plus.rochetta.fr/docs/reference/cli-ai-register/)

<a id="shared-options"></a>
## Options every command shares

Commander, the argument parser BMAD+ uses, provides `-V, --version` and `-h, --help` on the program, and `bmad-plus help <command>` or `bmad-plus <command> --help` for any command. The other shared options are declared command by command, so this table shows exactly where each one exists.

**Shared options by command**

| Command | `-d, --directory <path>` | `-y, --yes` | `-l, --lang <code>` | `--json` |
| --- | --- | --- | --- | --- |
| `install` | ✓ | ✓ | ✓ | – |
| `update` | ✓ | ✓ | ✓ | – |
| `uninstall` | ✓ | ✓ | ✓ | – |
| `doctor` | ✓ | – | ✓ | ✓ |
| `scan [path]` | ✓ | ✓ | ✓ | – |
| `memory [subcommand]` | ✓ | – | ✓ | – |
| `autoconfig` | ✓ | ✓ | ✓ | – |
| `mem <action> [query...]` | ✓ | – | – | ✓ |
| `update-check`, `update-policy`, `studio`, `nexus`, `swarm`, `uat`, `review`, `assurance`, `ai-register`, `intake` | ✓ | – | – | ✓ |

- `-d, --directory <path>` points the command at a project folder. Without it, the current folder is used. The cases where the folder holds no installation are explained on each page.
- `-y, --yes` accepts the defaults and skips every prompt (see below).
- `-l, --lang <code>` picks the language of the installer screens (see below).
- `--json` prints a machine-readable result instead of text, so a script can parse it.

<a id="languages"></a>
## Installer languages

The installer and uninstaller screens exist in ten languages. Every other command prints English.

**Values accepted by --lang**

| Code | Language |
| --- | --- |
| `en` | English |
| `fr` | Français |
| `es` | Español |
| `de` | Deutsch |
| `pt-br` | Português (Brasil) |
| `ru` | Русский |
| `zh` | 中文 (简体) |
| `he` | עברית |
| `ja` | 日本語 |
| `it` | Italiano |

- Interactive `install` without `--lang`: the first question is the language.
- `install --yes` without `--lang`: the screens are in English, and the communication language written to the configuration follows your system locale when it matches one of the ten, otherwise English.
- An unknown code is not an error: the screens fall back to English.
- `uninstall` and `update` without `--lang` use the language recorded at install time (`uiLanguage` in the manifest), then English.

<a id="non-interactive"></a>
## Non-interactive use with --yes

A script, a CI job or a pipe has no terminal to answer questions. `install`, `uninstall` and `update` refuse to start in that situation unless you pass `--yes`, instead of stopping halfway through a prompt. `scan` and `autoconfig` also accept `--yes` to take their recommended answers.

**What a refused start looks like** (Simulated)

```text
$ echo | npx bmad-plus install
This command requires a terminal. Run `npx bmad-plus install --yes` to proceed without prompts.
# Exit code 1; nothing was written.
```

Illustrative transcript, not captured from a real run. Source: tools/cli/i18n.js (noninteractive_requires_yes) and tools/cli/commands/install.js:55

**A fully unattended install**

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

> **Warning · --yes never guesses a tool** With `--yes` and no AI tool detected in the folder, `install` writes no instruction file at all. Pass `--tools <ids>` (or `--tools all`) to say which assistants to prepare. See the adapters page for the ids.

<a id="exit-codes"></a>
## Exit codes

Every command exits with 0 on success. An error that no command handles itself ends with the line `BMAD+: <message>` on the error stream and exit code 1. Beyond that, some commands use further codes to report a state a script can act on. After a command settles, BMAD+ releases the terminal input, so your shell prompt returns without Ctrl+C.

**Exit codes by command**

| Command | Code | Meaning |
| --- | --- | --- |
| `install`, `uninstall`, `update` | 1 | Any failure: no terminal and no `--yes`, version conflict, unreadable manifest, refused update. A cancelled `uninstall` or `update` prompt exits 0; a cancelled `install` exits 1. |
| `update-policy` | 1 | Invalid option combination or unreadable policy. |
| `doctor` | 1 | At least one check is an error. Warnings alone exit 0. |
| `update-check` | 1 | Status begins with `invalid-` (runtime, installation or policy). |
| `intake` | 1 / 2 | `check`: 1 when the file is invalid. `plan`: 2 when the intake is not ready. Other failures: 1. |
| `studio` | 2 / 1 | 2 = `needs-input`, 1 = error. |
| `swarm` | 2 / 1 | 2 = `needs-approval`, 1 = `incomplete` or error. |
| `nexus` | 1 | `verify` not passed, `launch` not completed, `collect` not completed, or error. |
| `uat` | 1 / 2 / 3 | `read` and `gate`: 0 passed, 1 failed, 2 no finished run, 3 answered another revision of the recipe. `lint` and `order`: 1 on errors or cycles. |
| `review` | 1 / 2 / 3 | `gate`: 0 clean, 1 findings, 2 incomplete. `continue`: 3 when the code moved. Other errors: 3. `anchor`: 1 when a finding is not located. |
| `assurance` | 1 / 3 | `run` and `verify`: 1 when a check failed or a claim is unsupported. Errors: 3. |
| `ai-register` | 1 / 3 | `check`: 1 only when the register is unreadable or invalid. Bad action or failed init: 3. |
| `mem` | 1 | Unknown action or failure. |

> **Tip · Gating a script on a verdict** Codes 2 and 3 are deliberate: they separate “not ready yet” or “stale” from “failed”. In CI, treat any non-zero code as a stop, and read the page of the command to know which kind of stop it is.

**See also**

- [Install, update, uninstall: the whole lifecycle](https://bmad-plus.rochetta.fr/docs/guides/install-lifecycle/)
- [The configuration file](https://bmad-plus.rochetta.fr/docs/reference/config-yaml/)
- [Supported tools and the files written for them](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)