BMAD-METHOD/docs/how-to/install-bmad.md

title	description	sidebar
How to Install BMad	Install, update, and pin BMad for local development, teams, and CI	order 1

Use npx bmad-method install to set up BMad in your project. One command handles first installs, upgrades, channel switching, and scripted CI runs. This page covers all of it.

When to Use This

• Starting a new project with BMad
• Adding or removing modules on an existing install
• Switching a module to main-HEAD or pinning to a specific release
• Scripting installs for CI pipelines, Dockerfiles, or enterprise rollouts

:::note[Prerequisites]

• Node.js 20+ (the installer requires it)
• Git (for cloning external modules)
• An AI tool such as Claude Code or Cursor — or install without one using --tools none

:::

First-time install (the fast path)

npx bmad-method install

The interactive flow asks you five things:

1. Installation directory (defaults to the current working directory)
2. Which modules to install (checkboxes for core, bmm, bmb, cis, gds, tea)
3. "Ready to install (all stable)?" — Yes accepts the latest released tag for every external module
4. Which AI tools/IDEs to integrate with (claude-code, cursor, and others)
5. Per-module config (name, language, output folder)

Accept the defaults and you land on the latest stable release of every module, configured for your chosen tool.

:::tip[Just want the newest prerelease?]

npx bmad-method@next install

Runs the prerelease installer, which ships a newer snapshot of core and bmm. More churn, fewer delays between development and release. :::

Picking a specific version

Two independent axes control what ends up on disk.

Axis 1: external module channels

Every external module — bmb, cis, gds, tea, and any community module — installs on one of three channels:

Channel	What gets installed	Who picks this
stable (default)	Highest released semver tag. Prereleases like v2.0.0-alpha.1 are excluded.	Most users
next	Main branch HEAD at install time	Contributors, early adopters
pinned	A specific tag you name	Enterprise installs, CI reproducibility

Channels are per-module. You can run bmb on next while leaving cis on stable — the flags below let you mix freely.

Axis 2: installer binary version

The bmad-method npm package itself has two dist-tags:

Command	What you get
npx bmad-method install (@latest)	Latest stable installer release
npx bmad-method@next install	Latest prerelease installer, auto-published on every push to main

The installer binary determines your core and bmm versions. Those two modules ship bundled inside the installer package rather than being cloned from separate repos.

Why core and bmm don't have their own channel

They're stapled to the installer binary you ran:

• npx bmad-method install → latest stable core and bmm
• npx bmad-method@next install → prerelease core and bmm
• node /path/to/local-checkout/tools/installer/bmad-cli.js install → whatever your local checkout has

--pin bmm=v6.3.0 and --next=bmm are silently ineffective against bundled modules, and the installer warns you when you try. A future release extracts bmm from the installer package; once that ships, bmm gets a proper channel selector like bmb has today.

Updating an existing install

Running npx bmad-method install in a directory that already contains _bmad/ gives you a menu:

Choice	What it does
Quick Update	Re-runs the install with your existing settings. Refreshes files, applies patches and minor stable upgrades, refuses major upgrades. Fast, non-interactive.
Modify Install	Full interactive flow. Add or remove modules, reconfigure settings, optionally review and switch channels for existing modules.

Upgrade prompts

When Modify detects a newer stable tag for a module you've installed on stable, it classifies the diff and prompts accordingly:

Upgrade type	Example	Default
Patch	v1.7.0 → v1.7.1	Y
Minor	v1.7.0 → v1.8.0	Y
Major	v1.7.0 → v2.0.0	N

Major defaults to N because breaking changes frequently surface as "instability" when they weren't expected. The prompt includes a GitHub release-notes URL so you can read what changed before accepting.

Under --yes, patch and minor upgrades apply automatically. Majors stay frozen — pass --pin <code>=<new-tag> to accept non-interactively.

Switching a module's channel

Interactively: choose Modify → answer Yes to "Review channel assignments?" → each external module offers Keep, Switch to stable, Switch to next, or Pin to a tag.

Via flags: the recipes in the next section cover the common cases.

Headless / CI installs

Flag reference

Flag	Purpose
--yes, -y	Skip all prompts; accept flag values + defaults
--directory <path>	Install into this directory (default: current working dir)
--modules <a,b,c>	Exact module set. Core is auto-added. Not a delta — list everything you want kept.
--tools <a,b> or --tools none	IDE/tool selection. none skips tool config entirely.
--action <type>	install, update, or quick-update. Defaults based on existing install state.
--custom-source <urls>	Install custom modules from Git URLs or local paths
--channel <stable|next>	Apply to all externals (aliased as --all-stable / --all-next)
--all-stable	Alias for --channel=stable
--all-next	Alias for --channel=next
--next=<code>	Put one module on next. Repeatable.
--pin <code>=<tag>	Pin one module to a specific tag. Repeatable.
--user-name, --communication-language, --document-output-language, --output-folder	Override per-user config defaults

Precedence when flags overlap: --pin beats --next= beats --channel / --all-* beats the registry default (stable).

:::note[Example resolution] --all-next --pin cis=v0.2.0 puts bmb, gds, and tea on next while pinning cis to v0.2.0. :::

Recipes

Default install — latest stable for everything:

npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code

Enterprise pin — reproducible byte-for-byte:

npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --pin bmb=v1.7.0 --pin cis=v0.2.0 \
  --tools claude-code

Bleeding edge — externals on main HEAD:

npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code

Add a module to an existing install (keep everything else):

npx bmad-method install --yes --action update \
  --modules bmm,bmb,gds \
  --tools none

Mix channels — bmb on next, gds on stable:

npx bmad-method install --yes --action update \
  --modules bmm,bmb,cis,gds \
  --next=bmb \
  --tools none

:::caution[Rate limit on shared IPs] Anonymous GitHub API calls are capped at 60/hour per IP. A single install hits the API once per external module to resolve the stable tag. Offices behind NAT, CI runner pools, and VPNs can collectively exhaust this.

Set GITHUB_TOKEN=<personal access token> in the environment to raise the limit to 5000/hour per account. Any public-repo-read PAT works; no scopes are required. :::

What got installed

After any install, _bmad/_config/manifest.yaml records exactly what's on disk:

modules:
  - name: bmb
    version: v1.7.0                       # the tag, or "main" for next
    channel: stable                       # stable | next | pinned
    sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
    source: external
    repoUrl: https://github.com/bmad-code-org/bmad-builder

The sha field is always populated. For reproducible installs, pass the same --modules + --pin / --next= combination on a fresh machine and you'll land on the same commits.

Troubleshooting

"Could not resolve stable tag" or "API rate limit exceeded"

You've hit GitHub's 60/hr anonymous limit. Set GITHUB_TOKEN and retry. If you already have a token set, it may be expired or rate-limited on its own budget — try a different token or wait for the hourly reset.

"Tag 'vX.Y.Z' not found"

The tag you passed to --pin doesn't exist in the module's repo. Check the repo's releases page on GitHub for valid tags.

A pinned install keeps upgrading

Pinned installs don't upgrade. Quick-update applies patches and minors on stable channel only; it won't touch pinned or next. If a pinned install changed, open _bmad/_config/manifest.yaml — channel: pinned plus a fixed version and sha should hold across runs unless you explicitly override via flags.

--pin bmm=X didn't do anything

bmm is a bundled module — --pin and --next= don't apply. Use npx bmad-method@next install for a prerelease core/bmm, or check out the bmad-bmm repo and run the installer locally to get unreleased changes.