590 lines
19 KiB
Markdown
590 lines
19 KiB
Markdown
# BMad CLI Tool
|
|
|
|
The BMad CLI handles installation and web bundling for the BMAD-METHOD framework. It compiles YAML agents into two distinct formats: **IDE-integrated agents** (filesystem-aware, customizable) and **web bundles** (self-contained, dependency-embedded).
|
|
|
|
## Table of Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Commands](#commands)
|
|
- [Installation System](#installation-system)
|
|
- [Installation Flow](#installation-flow)
|
|
- [IDE Support](#ide-support)
|
|
- [Custom Module Configuration](#custom-module-configuration)
|
|
- [Platform Specifics](#platform-specifics)
|
|
- [Manifest System](#manifest-system)
|
|
- [Advanced Features](#advanced-features)
|
|
- [Bundling System](#bundling-system)
|
|
- [Agent Compilation](#agent-compilation)
|
|
- [Architecture](#architecture)
|
|
- [Key Differences: Installation vs Bundling](#key-differences-installation-vs-bundling)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The CLI provides two primary functions:
|
|
|
|
1. **Installation**: Compiles agents from YAML and installs to IDE environments with full customization support
|
|
2. **Bundling**: Packages agents and dependencies into standalone web-ready XML files
|
|
|
|
Both use the same YAML→XML compilation engine but produce different outputs optimized for their environments.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Interactive installation
|
|
npm run install:bmad
|
|
|
|
# Direct CLI usage
|
|
node tools/cli/bmad-cli.js install --target /path/to/project --modules bmm,bmb --ides codex
|
|
|
|
# Flags:
|
|
# --target <path> Target project directory
|
|
# --modules <list> Comma-separated: bmm, bmb, cis
|
|
# --ides <list> Comma-separated IDE codes (see IDE Support)
|
|
# --non-interactive Skip all prompts
|
|
```
|
|
|
|
### Bundling
|
|
|
|
```bash
|
|
# Bundle all modules
|
|
npm run bundle
|
|
|
|
# Bundle specific items
|
|
node tools/cli/bundlers/bundle-web.js all # Everything
|
|
node tools/cli/bundlers/bundle-web.js module bmm # One module
|
|
node tools/cli/bundlers/bundle-web.js agent bmm pm # One agent
|
|
```
|
|
|
|
### Utilities
|
|
|
|
```bash
|
|
npm run bmad:status # Installation status
|
|
npm run validate:bundles # Validate web bundles
|
|
node tools/cli/regenerate-manifests.js # Regenerate agent-party.xml files
|
|
```
|
|
|
|
---
|
|
|
|
## Installation System
|
|
|
|
The installer is a multi-stage system that handles agent compilation, IDE integration, module configuration, platform-specific behaviors, and manifest generation.
|
|
|
|
### Installation Flow
|
|
|
|
```
|
|
1. Collect User Input
|
|
- Target directory, modules, IDEs
|
|
- Custom module configuration (via install-menu-config.yaml)
|
|
|
|
2. Pre-Installation
|
|
- Validate target, check conflicts, backup existing installations
|
|
- Resolve module dependencies (4-pass system)
|
|
|
|
3. Install Core + Modules
|
|
- Copy files to {target}/bmad/
|
|
- Compile agents: YAML → Markdown/XML (forWebBundle: false)
|
|
- Merge customize.yaml files if they exist
|
|
- Inject activation blocks based on agent capabilities
|
|
|
|
4. IDE Integration
|
|
- Initialize selected IDE handlers
|
|
- Generate IDE-specific artifacts (commands/rules/workflows)
|
|
- Execute platform-specific hooks (IDE+module combinations)
|
|
|
|
5. Generate Manifests
|
|
- manifest.yaml (installation metadata)
|
|
- workflow-manifest.csv (workflow catalog)
|
|
- agent-manifest.csv (agent metadata)
|
|
- task-manifest.csv (legacy)
|
|
- files-manifest.csv (all files with SHA256 hashes)
|
|
|
|
6. Validate & Finalize
|
|
- Verify file integrity, agent compilation, IDE artifacts
|
|
- Display summary and next steps
|
|
```
|
|
|
|
**Output Structure**:
|
|
|
|
```
|
|
{target}/
|
|
├── bmad/
|
|
│ ├── core/ # Always installed
|
|
│ ├── {module}/ # Selected modules
|
|
│ │ ├── agents/ # Compiled .md files
|
|
│ │ ├── workflows/
|
|
│ │ └── config.yaml
|
|
│ └── _cfg/ # Manifests
|
|
└── .{ide}/ # IDE-specific artifacts
|
|
└── ... # Format varies by IDE
|
|
```
|
|
|
|
### IDE Support
|
|
|
|
The installer supports **14 IDE environments** through a base-derived architecture. Each IDE handler extends `BaseIDE` and implements IDE-specific artifact generation.
|
|
|
|
**Supported IDEs** (as of v6-alpha):
|
|
|
|
| Code | Name | Artifact Location |
|
|
| ---------------- | ----------------- | ---------------------- |
|
|
| `codex` | Claude Code | `.claude/commands/` |
|
|
| `claude-code` | Claude Code (alt) | `.claude/commands/` |
|
|
| `windsurf` | Windsurf | `.windsurf/workflows/` |
|
|
| `cursor` | Cursor | `.cursor/rules/` |
|
|
| `cline` | Cline | `.clinerules/` |
|
|
| `github-copilot` | GitHub Copilot | `.github/copilot/` |
|
|
| `crush` | Crush | `.crush/` |
|
|
| `auggie` | Auggie | `.auggie/` |
|
|
| `gemini` | Google Gemini | `.gemini/` |
|
|
| `qwen` | Qwen | `.qwen/` |
|
|
| `roo` | Roo | `.roo/` |
|
|
| `trae` | Trae | `.trae/` |
|
|
| `iflow` | iFlow | `.iflow/` |
|
|
| `kilo` | Kilo | `.kilo/` |
|
|
|
|
**Handler Architecture**:
|
|
|
|
- Base class: `tools/cli/installers/lib/ide/_base-ide.js`
|
|
- Handler implementations: `tools/cli/installers/lib/ide/{ide-code}.js`
|
|
- Dynamic discovery: IDE manager scans directory and auto-registers handlers
|
|
- Each handler implements: `setup()`, `createArtifacts()`, `cleanup()`, `getAgentsFromBmad()`
|
|
|
|
**Adding New IDE Support**:
|
|
|
|
1. Create handler file: `tools/cli/installers/lib/ide/your-ide.js`
|
|
2. Extend `BaseIDE`, set `ideCode`, `ideName`, `artifactType`
|
|
3. Implement artifact generation methods
|
|
4. IDE auto-discovered on next run
|
|
|
|
### Custom Module Configuration
|
|
|
|
Modules define interactive configuration menus via `install-menu-config.yaml` files in their `_module-installer/` directories.
|
|
|
|
**Config File Location**:
|
|
|
|
- Core: `src/core/_module-installer/install-menu-config.yaml`
|
|
- Modules: `src/modules/{module}/_module-installer/install-menu-config.yaml`
|
|
|
|
**Configuration Types**:
|
|
|
|
- `select`: Radio button choices
|
|
- `multiselect`: Checkboxes
|
|
- `input`: Text input with validation
|
|
- `confirm`: Yes/no
|
|
|
|
**Variable Substitution**:
|
|
|
|
- `{project-root}` → Absolute target path
|
|
- `{directory_name}` → Project directory basename
|
|
- `{module}` → Current module name
|
|
- `{value:config_id}` → Reference another config value
|
|
|
|
**Config Persistence**:
|
|
|
|
- Values saved to module's `config.yaml`
|
|
- Existing values detected on reinstall
|
|
- User prompted: "Use existing or change?"
|
|
|
|
**Processor**: `tools/cli/installers/lib/core/config-collector.js`
|
|
|
|
### Platform Specifics
|
|
|
|
Platform specifics are **IDE+module combination hooks** that execute custom logic when specific IDE and module are installed together.
|
|
|
|
**Two-Layer Architecture**:
|
|
|
|
1. **Module-Level**: `src/modules/{module}/_module-installer/platform-specifics/{ide}.js`
|
|
- Module provides custom behavior for specific IDEs
|
|
- Example: BMM creates subagents when installed with Claude Code
|
|
|
|
2. **IDE-Level**: Embedded in IDE handler's `createArtifacts()` method
|
|
- IDE provides custom handling for specific modules
|
|
- Example: Windsurf configures cascade workflows for BMM
|
|
|
|
**Execution Timing**: After standard installation, before validation
|
|
|
|
**Common Use Cases**:
|
|
|
|
- Creating subagent variations (PM-technical, PM-market)
|
|
- Configuring IDE-specific workflow integrations
|
|
- Adding custom commands or rules based on module features
|
|
- Adjusting UI/UX for module-specific patterns
|
|
|
|
**Platform Registry**: `tools/cli/installers/lib/ide/shared/platform-codes.js`
|
|
|
|
### Manifest System
|
|
|
|
The installer generates **5 manifest files** in `{target}/bmad/_cfg/`:
|
|
|
|
**1. Installation Manifest** (`manifest.yaml`)
|
|
|
|
- Installation metadata: version, timestamps, target directory
|
|
- Installed modules and versions
|
|
- Integrated IDEs and their configurations
|
|
- User configuration values
|
|
|
|
**2. Workflow Manifest** (`workflow-manifest.csv`)
|
|
|
|
- Columns: module, workflow_path, workflow_name, description, scale_level
|
|
- Used by workflow command generators
|
|
- RFC 4180 compliant CSV format
|
|
|
|
**3. Agent Manifest** (`agent-manifest.csv`)
|
|
|
|
- Columns: module, agent_path, agent_name, role, identity_summary, communication_style, expertise, approach, responsibilities, workflows
|
|
- 10-column metadata for each agent
|
|
- Used by IDE integrations and documentation
|
|
|
|
**4. Task Manifest** (`task-manifest.csv`)
|
|
|
|
- Legacy compatibility (deprecated in v6)
|
|
- Columns: module, task_path, task_name, objective, agent
|
|
|
|
**5. Files Manifest** (`files-manifest.csv`)
|
|
|
|
- Complete file tracking with SHA256 hashes
|
|
- Columns: file_path, file_type, module, hash
|
|
- Enables integrity validation and change detection
|
|
|
|
**Generator**: `tools/cli/installers/lib/core/manifest-generator.js`
|
|
|
|
**Use Cases**:
|
|
|
|
- Update detection (compare current vs manifest hashes)
|
|
- Workflow command generation for IDEs
|
|
- Installation validation and integrity checks
|
|
- Rollback capability
|
|
|
|
### Advanced Features
|
|
|
|
**Dependency Resolution** (4-Pass System):
|
|
|
|
- Pass 1: Explicit dependencies from module metadata
|
|
- Pass 2: Template references in workflows
|
|
- Pass 3: Cross-module workflow/agent references
|
|
- Pass 4: Transitive dependencies
|
|
|
|
**Agent Activation Injection**:
|
|
|
|
- Detects which handlers each agent uses (workflow, exec, tmpl, data, action)
|
|
- Injects only needed handler fragments from `src/utility/models/fragments/`
|
|
- Keeps compiled agents lean and purpose-built
|
|
|
|
**Module Injection System**:
|
|
|
|
- Conditional content injection based on user config
|
|
- Can inject menu items, text blocks, workflow steps
|
|
- File: `tools/cli/installers/lib/ide/shared/module-injections.js`
|
|
|
|
**Conflict Resolution**:
|
|
|
|
- Detects existing installations
|
|
- Options: Update (preserve customizations), Backup (timestamp), Cancel
|
|
- Auto-backup to `.bmad-backup-{timestamp}` if selected
|
|
|
|
**Workflow Command Auto-Generation**:
|
|
|
|
- Reads workflow-manifest.csv
|
|
- Generates IDE commands for each workflow
|
|
- IDE-specific formatting (Claude Code .md, Windsurf YAML, etc.)
|
|
|
|
**Validation & Integrity**:
|
|
|
|
- Verifies all manifest files exist
|
|
- Validates file hashes against files-manifest.csv
|
|
- Checks agent compilation completeness
|
|
- Confirms IDE artifacts created
|
|
|
|
---
|
|
|
|
## Bundling System
|
|
|
|
Web bundling creates self-contained XML packages with all dependencies embedded for web deployment.
|
|
|
|
### Bundling Flow
|
|
|
|
```
|
|
1. Discover modules and agents from src/modules/
|
|
2. For each agent:
|
|
- Compile with YamlXmlBuilder (forWebBundle: true)
|
|
- Use web-bundle-activation-steps.xml fragment
|
|
- Resolve ALL dependencies recursively:
|
|
- Scan menu items for workflow references
|
|
- Load workflows → extract web_bundle section
|
|
- Find all file references (templates, data, sub-workflows)
|
|
- Wrap each in <file id="path"><![CDATA[...]]></file>
|
|
- Build consolidated bundle: agent + all deps
|
|
3. Output to: web-bundles/{module}/agents/{name}.xml
|
|
```
|
|
|
|
**Key Differences from Installation**:
|
|
|
|
- No customize.yaml merging (base agents only)
|
|
- No metadata (reduces file size)
|
|
- All dependencies bundled inline (no filesystem access)
|
|
- Uses web-specific activation fragment
|
|
- Output: Standalone XML files
|
|
|
|
**Output Structure**:
|
|
|
|
```
|
|
web-bundles/
|
|
├── bmm/
|
|
│ ├── agents/
|
|
│ │ ├── pm.xml
|
|
│ │ ├── architect.xml
|
|
│ │ ├── sm.xml
|
|
│ │ └── dev.xml
|
|
│ └── teams/
|
|
│ └── dev-team.xml
|
|
├── bmb/
|
|
│ └── agents/
|
|
│ └── bmad-builder.xml
|
|
└── cis/
|
|
└── agents/
|
|
└── creative-director.xml
|
|
```
|
|
|
|
**Bundler**: `tools/cli/bundlers/web-bundler.js`
|
|
|
|
---
|
|
|
|
## Agent Compilation
|
|
|
|
Both installation and bundling use the same YAML→XML compiler with different configurations.
|
|
|
|
### Compilation Engine
|
|
|
|
**Core File**: `tools/cli/lib/yaml-xml-builder.js`
|
|
|
|
**Process**:
|
|
|
|
1. Load YAML agent definition
|
|
2. Merge with customize.yaml (installation only)
|
|
3. Analyze agent to detect required handlers
|
|
4. Build activation block:
|
|
- IDE: Uses `activation-steps.xml` (filesystem-aware)
|
|
- Web: Uses `web-bundle-activation-steps.xml` (bundled files)
|
|
5. Convert to XML structure
|
|
6. Output as markdown (IDE) or standalone XML (web)
|
|
|
|
**Key Option Flags**:
|
|
|
|
- `forWebBundle: true` - Use web activation, omit metadata
|
|
- `includeMetadata: true` - Include build hash (IDE only)
|
|
- `skipActivation: true` - Omit activation (team bundles)
|
|
|
|
### Fragment System
|
|
|
|
Reusable XML fragments in `src/utility/models/fragments/`:
|
|
|
|
- `activation-steps.xml` - IDE activation (loads config.yaml at runtime)
|
|
- `web-bundle-activation-steps.xml` - Web activation (uses bundled files)
|
|
- `activation-rules.xml` - Validation rules (IDE only)
|
|
- `menu-handlers.xml` - Menu handler wrapper
|
|
- `handler-workflow.xml` - Workflow handler
|
|
- `handler-exec.xml` - Exec command handler
|
|
- `handler-tmpl.xml` - Template handler
|
|
- `handler-data.xml` - Data handler
|
|
- `handler-action.xml` - Action handler
|
|
|
|
**Dynamic Injection**: Agent analyzer detects which handlers are used, activation builder injects only those fragments.
|
|
|
|
### Input: Agent YAML
|
|
|
|
```yaml
|
|
agent:
|
|
metadata:
|
|
id: 'bmad/bmm/agents/pm.md'
|
|
name: 'PM'
|
|
title: 'Product Manager'
|
|
persona:
|
|
role: 'Product Manager'
|
|
identity: 'You are an experienced PM...'
|
|
menu:
|
|
- trigger: '*create-brief'
|
|
workflow: '{project-root}/bmad/bmm/workflows/.../workflow.yaml'
|
|
```
|
|
|
|
### Output: IDE (Markdown with XML)
|
|
|
|
````markdown
|
|
<!-- Powered by BMAD-CORE™ -->
|
|
|
|
# Product Manager
|
|
|
|
```xml
|
|
<agent id="..." name="PM">
|
|
<activation critical="MANDATORY">
|
|
<step n="2">Load {project-root}/bmad/bmm/config.yaml at runtime</step>
|
|
...
|
|
</activation>
|
|
<persona>...</persona>
|
|
<menu>...</menu>
|
|
</agent>
|
|
```
|
|
````
|
|
|
|
````
|
|
|
|
### Output: Web (Standalone XML)
|
|
|
|
```xml
|
|
<agent id="..." name="PM">
|
|
<activation critical="MANDATORY">
|
|
<step n="2">All dependencies bundled inline below</step>
|
|
...
|
|
</activation>
|
|
<persona>...</persona>
|
|
<menu>...</menu>
|
|
<bundled-files>
|
|
<file id="bmad/bmm/config.yaml"><![CDATA[...]]></file>
|
|
<file id="bmad/bmm/workflows/.../workflow.yaml"><![CDATA[...]]></file>
|
|
...
|
|
</bundled-files>
|
|
</agent>
|
|
````
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
tools/cli/
|
|
├── bmad-cli.js # Main CLI entry
|
|
├── commands/ # CLI command handlers
|
|
│ ├── install.js
|
|
│ ├── status.js
|
|
│ ├── list.js
|
|
│ ├── update.js
|
|
│ └── uninstall.js
|
|
├── bundlers/ # Web bundling
|
|
│ ├── bundle-web.js # CLI entry
|
|
│ └── web-bundler.js # WebBundler class
|
|
├── installers/
|
|
│ └── lib/
|
|
│ ├── core/ # Core installer logic
|
|
│ │ ├── installer.js
|
|
│ │ ├── manifest-generator.js
|
|
│ │ ├── manifest.js
|
|
│ │ ├── dependency-resolver.js
|
|
│ │ ├── config-collector.js
|
|
│ │ └── csv-parser.js
|
|
│ ├── modules/ # Module processing
|
|
│ │ └── manager.js
|
|
│ └── ide/ # IDE integrations
|
|
│ ├── _base-ide.js
|
|
│ ├── {14 IDE handlers}.js
|
|
│ ├── manager.js
|
|
│ └── shared/
|
|
│ ├── bmad-artifacts.js
|
|
│ ├── platform-codes.js
|
|
│ ├── module-injections.js
|
|
│ └── workflow-command-generator.js
|
|
├── lib/ # Shared compilation
|
|
│ ├── yaml-xml-builder.js # YAML→XML compiler
|
|
│ ├── activation-builder.js # Activation generator
|
|
│ ├── agent-analyzer.js # Handler detection
|
|
│ ├── xml-handler.js # Builder wrapper
|
|
│ └── paths.js
|
|
├── regenerate-manifests.js
|
|
└── test-yaml-builder.js
|
|
```
|
|
|
|
### Fragment Library
|
|
|
|
```
|
|
src/utility/models/fragments/
|
|
├── activation-steps.xml
|
|
├── web-bundle-activation-steps.xml
|
|
├── activation-rules.xml
|
|
├── menu-handlers.xml
|
|
└── handler-*.xml # 5 handler types
|
|
```
|
|
|
|
---
|
|
|
|
## Key Differences: Installation vs Bundling
|
|
|
|
| Aspect | Installation (IDE) | Bundling (Web) |
|
|
| ----------------------- | ----------------------------- | --------------------------------- |
|
|
| **Trigger** | `npm run install:bmad` | `npm run bundle` |
|
|
| **Entry Point** | `commands/install.js` | `bundlers/bundle-web.js` |
|
|
| **Compiler Flag** | `forWebBundle: false` | `forWebBundle: true` |
|
|
| **Output Format** | Markdown `.md` | Standalone XML `.xml` |
|
|
| **Output Location** | `{target}/bmad/` + IDE dirs | `web-bundles/` |
|
|
| **Customization** | Merges `customize.yaml` | Base agents only |
|
|
| **Dependencies** | Referenced by path | Bundled inline (CDATA) |
|
|
| **Activation Fragment** | `activation-steps.xml` | `web-bundle-activation-steps.xml` |
|
|
| **Filesystem Access** | Required | Not needed |
|
|
| **Build Metadata** | Included (hash) | Excluded |
|
|
| **Path Format** | `{project-root}` placeholders | Stripped, wrapped as `<file>` |
|
|
| **Use Case** | Local IDE development | Web deployment |
|
|
|
|
**Activation Differences**:
|
|
|
|
- **IDE**: Loads config.yaml at runtime from filesystem
|
|
- **Web**: Accesses bundled content via `<file id>` references
|
|
|
|
---
|
|
|
|
## Development Workflows
|
|
|
|
### Testing Compilation
|
|
|
|
```bash
|
|
# Test YAML→XML compiler
|
|
node tools/cli/test-yaml-builder.js
|
|
|
|
# Test installation
|
|
node tools/cli/bmad-cli.js install --target ./test-project --modules bmm --ides codex
|
|
|
|
# Test bundling
|
|
node tools/cli/bundlers/bundle-web.js agent bmm pm
|
|
|
|
# Validate bundles
|
|
npm run validate:bundles
|
|
```
|
|
|
|
### Adding New Menu Handlers
|
|
|
|
To add a new handler type (e.g., `validate-workflow`):
|
|
|
|
1. Create fragment: `src/utility/models/fragments/handler-validate-workflow.xml`
|
|
2. Update `agent-analyzer.js` to detect the new attribute
|
|
3. Update `activation-builder.js` to load/inject the fragment
|
|
4. Test with an agent using the handler
|
|
|
|
### Regenerating Manifests
|
|
|
|
```bash
|
|
# Regenerate agent-party.xml for all modules
|
|
node tools/cli/regenerate-manifests.js
|
|
|
|
# Location: src/modules/{module}/agents/agent-party.xml
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **Project Guide**: `CLAUDE.md`
|
|
- **BMM Workflows**: `src/modules/bmm/workflows/README.md`
|
|
- **Module Structure**: `src/modules/bmb/workflows/create-module/module-structure.md`
|
|
- **Agent Creation**: `src/modules/bmb/workflows/create-agent/README.md`
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- **Issues**: https://github.com/bmad-code-org/BMAD-METHOD/issues
|
|
- **Discord**: https://discord.gg/gk8jAdXWmj (#general-dev, #bugs-issues)
|
|
- **YouTube**: https://www.youtube.com/@BMadCode
|