CLI Commands

The BMad Method CLI provides commands for installing, managing, and monitoring your BMad installation. All commands are available through the bmad or bmad-method executables.

Installation

Install the BMad Method CLI globally or use it directly with npx:

npm install -g bmad-method
# or
npx bmad-method <command>

Global Options

All commands support the following global options:

--help

flag

Display help information for the command

--version

flag

Display the current version of bmad-method

Commands

install

Install BMAD Core agents and tools into your project.

bmad install [options]

Options

-d, --debug

flag

Enable debug output for manifest generation. Sets BMAD_DEBUG_MANIFEST=true for detailed logging during installation.

--directory

string

Installation directory path. Defaults to the current working directory.Example:

bmad install --directory /path/to/project

--modules

string

Comma-separated list of module IDs to install. Available modules include:

bmm - BMad Method Agile-AI Driven Development (default)
bmb - Builder module
tea - Test Architect
cis - Creative Intelligence
gds - Game Dev Studio

Example:

bmad install --modules bmm,bmb

--tools

string

Comma-separated list of tool/IDE IDs to configure. Use “none” to skip tool configuration.Supported tools:

claude-code - Claude Code IDE
cursor - Cursor IDE
windsurf - Windsurf IDE
none - Skip IDE integration

Example:

bmad install --tools claude-code,cursor
bmad install --tools none

--custom-content

string

Comma-separated list of paths to custom modules, agents, or workflows to include in the installation.Example:

bmad install --custom-content ./custom-agents,./my-workflows

--action

string

Action type for existing installations. Options:

install - Fresh installation
update - Full update with prompts
quick-update - Update modules preserving existing settings
compile-agents - Recompile agents with customizations

Example:

bmad install --action quick-update

--user-name

string

Name for agents to use when addressing you. Defaults to system username.Example:

bmad install --user-name "Alex"

--communication-language

string

Language for agent communication. Defaults to English.Example:

bmad install --communication-language "Spanish"

--document-output-language

string

Language for document output. Defaults to English.Example:

bmad install --document-output-language "French"

--output-folder

string

Output folder path relative to project root. Defaults to _bmad-output.Example:

bmad install --output-folder "docs/bmad"

-y, --yes

flag

Accept all defaults and skip prompts where possible. Useful for automated installations.Example:

bmad install -y --modules bmm --tools claude-code

Examples

Interactive installation (recommended for first-time users):

bmad install

The installer will guide you through:

Module selection
IDE/tool configuration
User preferences (name, languages)
Output folder locations

Non-interactive installation with defaults:

bmad install -y --modules bmm --tools claude-code

Update existing installation:

bmad install --action quick-update

Debug installation issues:

bmad install --debug

Expected Output

Successful installation:

✔ Installation directory: /path/to/project
✔ Selected modules: bmm
✔ Installing BMad Method Agile-AI Driven Development
✔ Configured IDE: claude-code
✔ Generated 47 command files in .claude/commands/
✓ Installation complete!

Quick update:

✔ Quick update complete!
ℹ Updated 1 modules with preserved settings (bmm)

status

Display BMAD installation status and module versions.

bmad status

Options

This command has no additional options.

Examples

Check installation status:

bmad status

Expected Output

When BMAD is installed:

╭─────────────────────────────────────────╮
│ BMAD Installation Status                │
├─────────────────────────────────────────┤
│ Version:     6.0.4                      │
│ Directory:   /path/to/project/_bmad     │
│ Installed:   2026-03-04                 │
├─────────────────────────────────────────┤
│ Modules:                                │
│  • bmm (v6.0.4) - BMad Method           │
├─────────────────────────────────────────┤
│ IDE Integrations:                       │
│  • Claude Code (.claude/commands/)      │
│  • 47 commands available                │
╰─────────────────────────────────────────╯

When BMAD is not installed:

⚠ No BMAD installation found in the current directory.
Expected location: /path/to/project/_bmad
Run "bmad install" to set up a new installation.

uninstall

Remove BMAD installation from the current project.

bmad uninstall [options]

The uninstall command preserves user artifacts (output folder contents) by default. You can explicitly choose to remove them during the interactive flow.

Options

-y, --yes

flag

Remove all BMAD components without prompting. User artifacts are always preserved in non-interactive mode.Example:

bmad uninstall -y

--directory

string

Project directory to uninstall from. Defaults to current directory in non-interactive mode, or prompts in interactive mode.Example:

bmad uninstall --directory /path/to/project

Examples

Interactive uninstall (recommended):

bmad uninstall

The uninstaller will:

Show current installation details
Let you select which components to remove:
- BMAD Modules & data (_bmad/)
- IDE integrations (command files)
- User artifacts (output folder) - WARNING: Contains your work
Confirm before proceeding

Non-interactive uninstall:

bmad uninstall -y

Removes:

BMAD modules and data
IDE integrations
Preserves user artifacts

Uninstall from specific directory:

bmad uninstall --directory /path/to/old-project

Expected Output

Interactive uninstall:

╭ BMAD Uninstall ────────────────────────────────╮
│                                                │
│ Current Installation                           │
│ Version: 6.0.4                                 │
│ Modules: bmm                                   │
│ IDE integrations: claude-code                  │
│                                                │
╰────────────────────────────────────────────────╯

? Select components to remove:
  ✓ BMAD Modules & data (_bmad/)
  ✓ IDE integrations
  ☐ User artifacts (_bmad-output/)

╭ !! DESTRUCTIVE ACTION !! ──────────────────────╮
│ 💀 This action is IRREVERSIBLE!                │
│ 💀 IDE configurations and modules will need    │
│    to be reinstalled.                          │
│ 💀 User artifacts are preserved unless         │
│    explicitly selected.                        │
╰────────────────────────────────────────────────╯

? Proceed with uninstall? (y/N)

✔ Removed IDE integrations (claude-code)
✔ Modules & data removed

╭ Summary ───────────────────────────────────────╮
│ IDE integrations cleaned                       │
│ Modules & data removed                         │
│ User artifacts preserved in _bmad-output/      │
╰────────────────────────────────────────────────╯

◇ To reinstall, run: npx bmad-method install

Non-interactive uninstall:

✔ Removed IDE integrations (claude-code)
✔ Modules & data removed

╭ Summary ───────────────────────────────────────╮
│ IDE integrations cleaned                       │
│ Modules & data removed                         │
│ User artifacts preserved in _bmad-output/      │
╰────────────────────────────────────────────────╯

Version Management

Checking for Updates

The CLI automatically checks for updates on startup and displays a notification if a newer version is available:

╭ Update Available ──────────────────────────────╮
│ You are using version 6.0.3 but 6.0.4 is      │
│ available.                                     │
│                                                │
│ To update, exit and first run:                │
│   npm cache clean --force &&                   │
│   npx bmad-method@latest install              │
╰────────────────────────────────────────────────╯

Beta Versions

To install beta versions, use the beta tag:

npx bmad-method@beta install

Exit Codes

All commands use standard exit codes:

0 - Success
1 - Error or failure

Environment Variables

BMAD_DEBUG_MANIFEST

boolean

Enable debug output for manifest generation. Set automatically by the --debug flag.Example:

export BMAD_DEBUG_MANIFEST=true
bmad install

BMAD_DEBUG

boolean

Enable general debug output including error stack traces.Example:

export BMAD_DEBUG=true
bmad status

Troubleshooting

Installation fails with permission errors

Ensure you have write permissions to the target directory:

bmad install --directory ~/my-project

Commands not found after installation

Restart your IDE or reload the window. Most IDEs cache command files and require a refresh.

Update not working

Clear npm cache and reinstall:

npm cache clean --force
npx bmad-method@latest install

Debug installation issues

Run with debug flag to see detailed output:

bmad install --debug

For status command errors:

export BMAD_DEBUG=true
bmad status

API Reference

Agents

Modules

Installation

Global Options

Commands

install

Options

Examples

Expected Output

status

Options

Examples

Expected Output

uninstall

Options

Examples

Expected Output

Version Management

Checking for Updates

Beta Versions

Exit Codes

Environment Variables

Troubleshooting

Installation fails with permission errors

Commands not found after installation

Update not working

Debug installation issues

Build docs developers (and LLMs) love

API Reference

Agents

Modules

Documentation Index

​Installation

​Global Options

​Commands

​install

​Options

​Examples

​Expected Output

​status

​Options

​Examples

​Expected Output

​uninstall

​Options

​Examples

​Expected Output

​Version Management

​Checking for Updates

​Beta Versions

​Exit Codes

​Environment Variables

​Troubleshooting

​Installation fails with permission errors

​Commands not found after installation

​Update not working

​Debug installation issues

Build docs developers (and LLMs) love

Installation

Global Options

Commands

install

Options

Examples

Expected Output

status

Options

Examples

Expected Output

uninstall

Options

Examples

Expected Output

Version Management

Checking for Updates

Beta Versions

Exit Codes

Environment Variables

Troubleshooting

Installation fails with permission errors

Commands not found after installation

Update not working

Debug installation issues