124 lines
5.0 KiB
Markdown
124 lines
5.0 KiB
Markdown
---
|
|
title: bmad-module CLI
|
|
description: Reference for the bmad-module command — install, update, remove, and list BMad community/custom modules from inside a project.
|
|
sidebar:
|
|
order: 7
|
|
---
|
|
|
|
`bmad-module` installs, updates, removes, and lists **community and custom BMad modules** in a project that already has BMad installed (a `_bmad/` directory). It is the command behind the `bmad-module` skill, and it mirrors the official installer's behavior for custom modules so a skill-driven install lands the same on-disk state.
|
|
|
|
Run it from your project root (the directory containing `_bmad/`), or point it elsewhere with `--project-dir`.
|
|
|
|
## Commands
|
|
|
|
```
|
|
bmad-module install <source> [--ref <ref>] [--channel <c>] [--module <code>] [--set <code>.<key>=<v>] [--dry-run]
|
|
bmad-module update <code|--all> [--ref <ref>] [--channel <c>] [--set <code>.<key>=<v>]
|
|
bmad-module remove <code> [--purge]
|
|
bmad-module list [--json]
|
|
```
|
|
|
|
### install `<source>`
|
|
|
|
Resolve a module from `<source>`, copy it into `_bmad/<code>/`, generate its config and agent roster, create its declared working directories, and distribute its skills to the coding assistants (IDEs) you chose at `bmad install` time.
|
|
|
|
`<source>` may be:
|
|
|
|
- A GitHub shorthand — `acme/acme-devlog`
|
|
- A full Git URL — `https://github.com/acme/acme-devlog` (optionally with `@ref` or `/tree/<ref>`)
|
|
- A local path — `./examples/minimal/acme-md-lint`
|
|
- A legacy `marketplace.json` repo — `bmad-code-org/bmad-module-game-dev-studio`
|
|
|
|
| Flag | Description |
|
|
| --- | --- |
|
|
| `--ref <ref>` | Clone a specific git tag/branch/commit. Implies `--channel pinned`. |
|
|
| `--channel <c>` | Release channel: `stable`, `next`, or `pinned` (see [Channels](#channels)). |
|
|
| `--module <code>` | Pick one module by `code` when a legacy `marketplace.json` repo resolves to more than one. |
|
|
| `--set <code>.<key>=<v>` | Override a module config answer. Repeatable. |
|
|
| `--dry-run` | Print the resolved install plan without writing anything. |
|
|
|
|
### update `<code>` | `--all`
|
|
|
|
Re-resolve an installed module and atomically swap in the new version. Aborts (exit `80`) if you have locally modified tracked files, so your edits are never silently overwritten.
|
|
|
|
| Flag | Description |
|
|
| --- | --- |
|
|
| `--all` | Update every installed community/custom module instead of a single `<code>`. |
|
|
| `--ref <ref>` | Update to a specific git ref. |
|
|
| `--channel <c>` | Switch/track a release channel (`stable`, `next`, `pinned`). |
|
|
| `--set <code>.<key>=<v>` | Override a module config answer. Repeatable. |
|
|
|
|
### remove `<code>`
|
|
|
|
Remove an installed module: delete `_bmad/<code>/`, prune its entries from the central config and help catalog, and remove its skills from your IDE directories.
|
|
|
|
| Flag | Description |
|
|
| --- | --- |
|
|
| `--purge` | Also delete the module's user customizations under `_bmad/custom/` (e.g. `_bmad/custom/<skill>.toml`). Without `--purge`, customizations are left intact. |
|
|
|
|
### list
|
|
|
|
List installed community/custom modules with their code, version, channel, and source.
|
|
|
|
| Flag | Description |
|
|
| --- | --- |
|
|
| `--json` | Emit machine-readable JSON instead of a formatted table. |
|
|
|
|
## Global flags
|
|
|
|
| Flag | Description |
|
|
| --- | --- |
|
|
| `--project-dir <path>` | Project root containing `_bmad/` (default: current directory). |
|
|
|
|
## Channels
|
|
|
|
`bmad-module` mirrors the official installer's channel semantics:
|
|
|
|
- **`stable`** — the latest non-prerelease GitHub release tag. Falls back to `next` (with a note) when the repo has no tags, isn't a GitHub repo, or the tags API is unreachable.
|
|
- **`next`** — the repository's default branch (`main`).
|
|
- **`pinned`** — the exact `--ref` you supply (or an `@ref` / `/tree/<ref>` parsed from the source). `--channel pinned` without a `--ref` falls back to `next`.
|
|
|
|
An explicit `--ref` (or an `@ref` in the source) implies `pinned`. An unknown `--channel` value is rejected with a usage error rather than silently tracking `next`.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Install from GitHub shorthand
|
|
bmad-module install acme/acme-devlog
|
|
|
|
# Install a local module
|
|
bmad-module install ./examples/minimal/acme-md-lint
|
|
|
|
# Pin to a release tag
|
|
bmad-module install https://github.com/acme/acme-devlog --ref v0.4.0
|
|
|
|
# Install a legacy marketplace.json module
|
|
bmad-module install bmad-code-org/bmad-module-game-dev-studio
|
|
|
|
# Override a config answer at install time
|
|
bmad-module install acme/acme-devlog --set devlog.author="Ada Lovelace"
|
|
|
|
# List, update, and remove
|
|
bmad-module list
|
|
bmad-module update devlog
|
|
bmad-module update --all
|
|
bmad-module remove mdlint --purge
|
|
```
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| `0` | Success |
|
|
| `2` | Usage error (bad arguments, unknown flag/channel) |
|
|
| `5` | Skill runtime files missing/corrupt — reinstall the skill |
|
|
| `10` | No `_bmad/` directory in the project |
|
|
| `20` | Missing or invalid `plugin.json` |
|
|
| `21` | Reserved `bmad.code` |
|
|
| `30` | Prefix collision with an existing module |
|
|
| `50` | Filesystem commit failed |
|
|
| `60` | Network / git clone failed |
|
|
| `70` | Path traversal detected in a manifest path |
|
|
| `80` | Update aborted: locally modified files |
|
|
| `90` | No such installed module |
|