BMAD CLI

Version: 6.2.0
Terminal interface for AARDVARQ Task Refinement Pipeline

The BMAD CLI provides a fast, terminal-based interface for interacting with AARDVARQ's Task Refinement Pipeline. Submit tasks, respond to gap questions, monitor pipeline status, and automate workflows without leaving your development environment.

Features

• ⚡ Fast Task Submission - Submit tasks in seconds
• 🤖 Interactive Q&A - Answer gap questions with intelligent suggestions
• 📊 Real-time Monitoring - Watch pipeline status and gap identification in real-time
• 📝 Template System - Use templates for common task types
• 📈 Analytics - View gap patterns and pipeline throughput
• 🔄 Automation Ready - Script-friendly with JSON/YAML support

Installation

Global Installation (Recommended)

npm install -g @aardvarq/bmad-cli

Local Development

git clone <repo>
cd bmad-cli
npm install
npm link

Shell Completion

Bash

# Add to ~/.bashrc or ~/.bash_profile
source <(bmad completion bash)
# Or manually:
source /path/to/bmad-cli/completions/bmad.bash

Zsh

# Add to ~/.zshrc
source <(bmad completion zsh)
# Or manually:
source /path/to/bmad-cli/completions/bmad.zsh

PowerShell

# Add to $PROFILE
. .\bmad-cli\completions\bmad.ps1

Quick Start

1. Authenticate

bmad auth login
# Enter path to your Firebase service account JSON file

2. Submit a Task

# Simple submission
bmad submit "Add user authentication feature"

# With template
bmad submit "Add payment processing" --template integration --var service=Stripe

# Interactive mode
bmad submit --interactive

# From file
bmad submit --file task.yaml

3. Answer Gap Questions

# Interactive answering
bmad answer --task <task-id>

# From file
bmad answer --file answers.yaml --task <task-id>

# List pending questions
bmad questions --task <task-id>

4. Monitor Pipeline

# View pipeline status
bmad pipeline status

# Watch gaps in real-time
bmad gaps watch --task <task-id>

# View task details
bmad pipeline status --task <task-id>

Command Reference

Authentication

bmad auth login          # Authenticate with Firebase
bmad auth logout         # Clear stored credentials
bmad auth status         # Check authentication status

Task Submission

bmad submit [description]              # Submit a new task
  --template <name>                     # Use a task template
  --var <key=value...>                  # Template variables
  --file <path>                         # Load from YAML/JSON file
  --interactive                         # Interactive wizard
  --from-commit                         # Extract from git commit
  --priority <level>                    # Task priority
  --dry-run                             # Validate without submitting

Gap Q&A

bmad answer                             # Answer gap questions
  --session <id>                        # Q&A session ID
  --task <id>                           # Task ID (finds active session)
  --file <path>                         # Load answers from file
  --interactive                         # Interactive mode

bmad questions                          # List pending questions
  --task <id>                           # Task ID
  --severity <level>                    # Filter by severity
  --dimension <type>                    # Filter by dimension

Pipeline Management

bmad pipeline status                    # View pipeline status
  --task <id>                           # Specific task
  --all                                 # Include completed
  --json                                # JSON output

bmad pipeline list                      # List tasks
  --stage <stage>                       # Filter by stage
  --priority <priority>                 # Filter by priority
  --limit <number>                      # Limit results

bmad pipeline upgrade                   # Upgrade task to next stage
  --task <id>                           # Task ID
  --force                               # Force upgrade

bmad pipeline cancel                    # Cancel a task
  --task <id>                           # Task ID
  --reason <reason>                     # Cancellation reason

Gap Tracking

bmad gaps watch                         # Watch gaps in real-time
  --task <id>                           # Task ID

bmad gaps list                          # List all gaps
  --task <id>                           # Task ID
  --severity <level>                    # Filter by severity
  --unanswered                          # Show only unanswered
  --json                                # JSON output

bmad gaps show                           # Show gap details
  --gap <id>                            # Gap ID

Reviews

bmad review show                         # Show review details
  --task <id>                           # Task ID
  --agent <name>                        # Specific agent
  --output <type>                       # Output type (summary/full/spec)
  --json                                # JSON output

bmad review conversation                 # Show agent conversation
  --task <id>                           # Task ID
  --full                                # Show full conversation

Templates

bmad template list                      # List templates
  --built-in                           # Built-in only
  --custom                             # Custom only

bmad template show <name>               # Show template details

bmad template create <name>             # Create template
  --from-task <id>                     # Create from task
  --interactive                        # Interactive wizard

bmad template delete <name>             # Delete template

Analytics

bmad analytics gaps                     # Analyze gap patterns
  --last <period>                      # Time period (7d, 30d, 90d)
  --dimension <type>                   # Filter by dimension
  --json                               # JSON output

bmad analytics throughput               # View throughput metrics
  --last <period>                      # Time period

bmad analytics agents                   # View agent performance
  --last <period>                      # Time period

Configuration

bmad config get [key]                   # Get configuration value
bmad config set <key> <value>          # Set configuration value
bmad config list                        # List all configuration
bmad config reset                       # Reset to defaults
  --key <key>                          # Reset specific key

Configuration

Configuration is stored in ~/.bmad/config.json. Key settings:

{
  "pipeline": {
    "minimumCompleteness": 85,
    "criticalGapsRequired": true,
    "autoSubmitThreshold": 95
  },
  "output": {
    "format": "table",
    "colorEnabled": true,
    "verbosity": "normal"
  },
  "suggestions": {
    "enabled": true,
    "similarityThreshold": 0.7,
    "maxSuggestions": 3
  }
}

Templates

Built-in Templates

• feature-addition - Standard template for adding new features
• bug-fix - Template for bug fix tasks
• integration - Template for third-party integrations
• refactor - Template for code refactoring tasks

Using Templates

# Submit with template
bmad submit "Add OAuth login" --template feature-addition --var feature=OAuth

# Create custom template
bmad template create my-template --interactive

# Create from existing task
bmad template create my-template --from-task <task-id>

File Formats

Task Submission File

# task.yaml
description: Add multi-currency support to billing
priority: high

preAnswers:
  target_users: "Small business owners, solopreneurs"
  mvp_scope: "USD, EUR, GBP only"
  api_integration: "Use Stripe multi-currency APIs"

businessContext:
  justification: "Enable EU market expansion"
  roi: "30% revenue increase projected"

technicalContext:
  security: "PCI DSS compliance required"
  performance: "Currency conversion < 100ms"

Answer File

# answers.yaml
questions:
  q-gap-001:
    answer: "Target users are small business owners with 1-10 employees"
  q-gap-002:
    answer: "MVP will support USD, EUR, GBP. Additional currencies in Phase 2"
    format: text
  q-gap-003:
    answer:
      - "Handle rate fluctuations with daily updates"
      - "Round to 2 decimal places"
      - "Display conversion fees transparently"
    format: list

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GOOGLE_APPLICATION_CREDENTIALS | Path to service account JSON | - | | BMAD_PROJECT_ID | Firebase project ID | - | | BMAD_DEBUG | Enable debug output | false | | BMAD_CONFIG_PATH | Custom config file path | ~/.bmad/config.json | | BMAD_TEMPLATE_PATH | Custom template directory | ~/.bmad/templates | | BMAD_NO_COLOR | Disable colored output | false |

Development

Building

npm run build

Testing

npm test
npm run test:coverage

Linting

npm run lint
npm run format

Troubleshooting

Authentication Issues

# Check authentication status
bmad auth status

# Re-authenticate
bmad auth logout
bmad auth login

Connection Issues

# Enable debug mode
export BMAD_DEBUG=true
bmad pipeline status

# Check Firebase configuration
bmad config get projectId

License

MIT

Documentation

• API Reference - Complete command reference
• Common Workflows - Practical examples and workflows
• Troubleshooting Guide - Common issues and solutions
• Firebase Testing Guide - Firebase integration guide

Support

For issues and questions, please refer to the Troubleshooting Guide or contact the development team.