docs(bmad-module): add CLI reference page
Document the bmad-module command (install/update/remove/list), every flag, channel semantics, examples, and exit codes under docs/reference/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
pbean
parent
e76b268ee9
commit
cbf87c414d
|
|
@ -0,0 +1,123 @@
|
|||
---
|
||||
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 |
|
||||
Loading…
Reference in New Issue