CLI Commands

Complete reference for bmad-method CLI commands and options

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:

1. Module selection
2. IDE/tool configuration
3. User preferences (name, languages)
4. 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:

1. Show current installation details
2. Let you select which components to remove:
   • BMAD Modules & data (_bmad/)
   • IDE integrations (command files)
   • User artifacts (output folder) - WARNING: Contains your work
3. 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