BMAD-METHOD/docs/reference/bmad-module-cli.md

title	description	sidebar
bmad-module CLI	Reference for the bmad-module command — install, update, remove, and list BMad community/custom modules from inside a project.	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).
--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

# 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