From 6030c8f53f0fab7b0188183a30607853597444f5 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 8 Feb 2026 01:17:41 -0700 Subject: [PATCH] fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides - Move non-interactive-installation.md into how-to/ directory so it appears in the sidebar navigation (was orphaned at docs root) - Rewrite the page based on editorial review: consolidate redundant sections, add missing how-to structure (prerequisites, "What You Get"), condense installation modes from 5 subsections to a table, cut speculative examples - Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3), then the rest following user journey order - Fix README link to point to docs site instead of repo-internal markdown path Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- docs/how-to/customize-bmad.md | 2 +- docs/how-to/established-projects.md | 2 +- docs/how-to/get-answers-about-bmad.md | 2 +- docs/how-to/install-bmad.md | 2 +- docs/how-to/non-interactive-installation.md | 171 +++++++++++ docs/how-to/quick-fixes.md | 2 +- docs/how-to/shard-large-documents.md | 2 +- docs/how-to/upgrade-to-v6.md | 2 +- docs/non-interactive-installation.md | 312 -------------------- 10 files changed, 179 insertions(+), 320 deletions(-) create mode 100644 docs/how-to/non-interactive-installation.md delete mode 100644 docs/non-interactive-installation.md diff --git a/README.md b/README.md index 6e1f3a9b0..e36d6e36a 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsu npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes ``` -See [Non-Interactive Installation Guide](docs/non-interactive-installation.md) for all available options. +See [Non-Interactive Installation Guide](http://docs.bmad-method.org/how-to/non-interactive-installation/) for all available options. > **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask it questions like: diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index 0daadd0e3..6b6016671 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -2,7 +2,7 @@ title: "How to Customize BMad" description: Customize agents, workflows, and modules while preserving update compatibility sidebar: - order: 5 + order: 7 --- Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates. diff --git a/docs/how-to/established-projects.md b/docs/how-to/established-projects.md index 1ba5e02ef..ef9acf704 100644 --- a/docs/how-to/established-projects.md +++ b/docs/how-to/established-projects.md @@ -2,7 +2,7 @@ title: "Established Projects" description: How to use BMad Method on existing codebases sidebar: - order: 4 + order: 6 --- Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects. diff --git a/docs/how-to/get-answers-about-bmad.md b/docs/how-to/get-answers-about-bmad.md index 65d9da910..7e1c57ca1 100644 --- a/docs/how-to/get-answers-about-bmad.md +++ b/docs/how-to/get-answers-about-bmad.md @@ -2,7 +2,7 @@ title: "How to Get Answers About BMad" description: Use an LLM to quickly answer your own BMad questions sidebar: - order: 2 + order: 4 --- If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working. diff --git a/docs/how-to/install-bmad.md b/docs/how-to/install-bmad.md index 15e7d362c..a7249ac48 100644 --- a/docs/how-to/install-bmad.md +++ b/docs/how-to/install-bmad.md @@ -7,7 +7,7 @@ sidebar: Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools. -If you want to use a non interactive installer and provide all install options on the command line, see [this guide](../non-interactive-installation.md). +If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md). ## When to Use This diff --git a/docs/how-to/non-interactive-installation.md b/docs/how-to/non-interactive-installation.md new file mode 100644 index 000000000..e9122ecdb --- /dev/null +++ b/docs/how-to/non-interactive-installation.md @@ -0,0 +1,171 @@ +--- +title: Non-Interactive Installation +description: Install BMad using command-line flags for CI/CD pipelines and automated deployments +sidebar: + order: 2 +--- + +Use command-line flags to install BMad non-interactively. This is useful for: + +## When to Use This + +- Automated deployments and CI/CD pipelines +- Scripted installations +- Batch installations across multiple projects +- Quick installations with known configurations + +:::note[Prerequisites] +Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm). +::: + +## Available Flags + +### Installation Options + +| Flag | Description | Example | +|------|-------------|---------| +| `--directory ` | Installation directory | `--directory ~/projects/myapp` | +| `--modules ` | Comma-separated module IDs | `--modules bmm,bmb` | +| `--tools ` | Comma-separated tool/IDE IDs (use `none` to skip) | `--tools claude-code,cursor` or `--tools none` | +| `--custom-content ` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` | +| `--action ` | Action for existing installations: `install` (default), `update`, `quick-update`, or `compile-agents` | `--action quick-update` | + +### Core Configuration + +| Flag | Description | Default | +|------|-------------|---------| +| `--user-name ` | Name for agents to use | System username | +| `--communication-language ` | Agent communication language | English | +| `--document-output-language ` | Document output language | English | +| `--output-folder ` | Output folder path | _bmad-output | + +### Other Options + +| Flag | Description | +|------|-------------| +| `-y, --yes` | Accept all defaults and skip prompts | +| `-d, --debug` | Enable debug output for manifest generation | + +## Module IDs + +Available module IDs for the `--modules` flag: + +- `bmm` — BMad Method Master +- `bmb` — BMad Builder + +Check the [BMad registry](https://github.com/bmad-code-org) for available external modules. + +## Tool/IDE IDs + +Available tool IDs for the `--tools` flag: + +**Preferred:** `claude-code`, `cursor`, `windsurf` + +Run `npx bmad-method install` interactively once to see the full current list of supported tools, or check the [platform codes configuration](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml). + +## Installation Modes + +| Mode | Description | Example | +|------|-------------|---------| +| Fully non-interactive | Provide all flags to skip all prompts | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` | +| Semi-interactive | Provide some flags; BMad prompts for the rest | `npx bmad-method install --directory . --modules bmm` | +| Defaults only | Accept all defaults with `-y` | `npx bmad-method install --yes` | +| Without tools | Skip tool/IDE configuration | `npx bmad-method install --modules bmm --tools none` | + +## Examples + +### CI/CD Pipeline Installation + +```bash +#!/bin/bash +# install-bmad.sh + +npx bmad-method install \ + --directory "${GITHUB_WORKSPACE}" \ + --modules bmm \ + --tools claude-code \ + --user-name "CI Bot" \ + --communication-language English \ + --document-output-language English \ + --output-folder _bmad-output \ + --yes +``` + +### Update Existing Installation + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action update \ + --modules bmm,bmb,custom-module +``` + +### Quick Update (Preserve Settings) + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action quick-update +``` + +### Installation with Custom Content + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --modules bmm \ + --custom-content ~/my-custom-module,~/another-module \ + --tools claude-code +``` + +## What You Get + +- A fully configured `_bmad/` directory in your project +- Compiled agents and workflows for your selected modules and tools +- A `_bmad-output/` folder for generated artifacts + +## Validation and Error Handling + +BMad validates all provided flags: + +- **Directory** — Must be a valid path with write permissions +- **Modules** — Warns about invalid module IDs (but won't fail) +- **Tools** — Warns about invalid tool IDs (but won't fail) +- **Custom Content** — Each path must contain a valid `module.yaml` file +- **Action** — Must be one of: `install`, `update`, `quick-update`, `compile-agents` + +Invalid values will either: +1. Show an error and exit (for critical options like directory) +2. Show a warning and skip (for optional items like custom content) +3. Fall back to interactive prompts (for missing required values) + +:::tip[Best Practices] +- Use absolute paths for `--directory` to avoid ambiguity +- Test flags locally before using in CI/CD pipelines +- Combine with `-y` for truly unattended installations +- Use `--debug` if you encounter issues during installation +::: + +## Troubleshooting + +### Installation fails with "Invalid directory" + +- The directory path must exist (or its parent must exist) +- You need write permissions +- The path must be absolute or correctly relative to the current directory + +### Module not found + +- Verify the module ID is correct +- External modules must be available in the registry + +### Custom content path invalid + +Ensure each custom content path: +- Points to a directory +- Contains a `module.yaml` file in the root +- Has a `code` field in the `module.yaml` + +:::note[Still stuck?] +Run with `--debug` for detailed output, try interactive mode to isolate the issue, or report at . +::: diff --git a/docs/how-to/quick-fixes.md b/docs/how-to/quick-fixes.md index b543b2154..4bb870908 100644 --- a/docs/how-to/quick-fixes.md +++ b/docs/how-to/quick-fixes.md @@ -2,7 +2,7 @@ title: "Quick Fixes" description: How to make quick fixes and ad-hoc changes sidebar: - order: 3 + order: 5 --- Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad Method or Quick Flow. diff --git a/docs/how-to/shard-large-documents.md b/docs/how-to/shard-large-documents.md index 27b619fa3..67a97a3ff 100644 --- a/docs/how-to/shard-large-documents.md +++ b/docs/how-to/shard-large-documents.md @@ -2,7 +2,7 @@ title: "Document Sharding Guide" description: Split large markdown files into smaller organized files for better context management sidebar: - order: 7 + order: 8 --- Use the `shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management. diff --git a/docs/how-to/upgrade-to-v6.md b/docs/how-to/upgrade-to-v6.md index df0cd5c18..c631db84e 100644 --- a/docs/how-to/upgrade-to-v6.md +++ b/docs/how-to/upgrade-to-v6.md @@ -2,7 +2,7 @@ title: "How to Upgrade to v6" description: Migrate from BMad v4 to v6 sidebar: - order: 6 + order: 3 --- Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance. diff --git a/docs/non-interactive-installation.md b/docs/non-interactive-installation.md deleted file mode 100644 index 0a13a4291..000000000 --- a/docs/non-interactive-installation.md +++ /dev/null @@ -1,312 +0,0 @@ ---- -title: Non-Interactive Installation -description: Install BMad using command-line flags for CI/CD pipelines and automated deployments ---- - -BMad now supports non-interactive installation through command-line flags. This is particularly useful for: - -- Automated deployments and CI/CD pipelines -- Scripted installations -- Batch installations across multiple projects -- Quick installations with known configurations - -## Installation Modes - -### 1. Fully Interactive (Default) - -Run without any flags to use the traditional interactive prompts: - -```bash -npx bmad-method install -``` - -### 2. Fully Non-Interactive - -Provide all required flags to skip all prompts: - -```bash -npx bmad-method install \ - --directory /path/to/project \ - --modules bmm,bmb \ - --tools claude-code,cursor \ - --user-name "John Doe" \ - --communication-language English \ - --document-output-language English \ - --output-folder _bmad-output -``` - -### 3. Semi-Interactive (Graceful Fallback) - -Provide some flags and let BMad prompt for the rest: - -```bash -npx bmad-method install \ - --directory /path/to/project \ - --modules bmm -``` - -In this case, BMad will: -- Use the provided directory and modules -- Prompt for tool selection -- Prompt for core configuration - -### 4. Quick Install with Defaults - -Use the `-y` or `--yes` flag to accept all defaults: - -```bash -npx bmad-method install --yes -``` - -This will: -- Install to the current directory -- Skip custom content prompts -- Use default values for all configuration -- Use previously configured tools (or skip tool configuration if none exist) - -### 5. Install Without Tools - -To skip tool/IDE configuration entirely: - -**Option 1: Use --tools none** -```bash -npx bmad-method install --directory ~/myapp --modules bmm --tools none -``` - -**Option 2: Use --yes flag (if no tools were previously configured)** -```bash -npx bmad-method install --yes -``` - -**Option 3: Omit --tools and select "None" in the interactive prompt** -```bash -npx bmad-method install --directory ~/myapp --modules bmm -# Then select "⚠ None - I am not installing any tools" when prompted -``` - -## Available Flags - -### Installation Options - -| Flag | Description | Example | -|------|-------------|---------| -| `--directory ` | Installation directory | `--directory ~/projects/myapp` | -| `--modules ` | Comma-separated module IDs | `--modules bmm,bmb` | -| `--tools ` | Comma-separated tool/IDE IDs (use "none" to skip) | `--tools claude-code,cursor` or `--tools none` | -| `--custom-content ` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` | -| `--action ` | Action for existing installations | `--action quick-update` | - -### Core Configuration - -| Flag | Description | Default | -|------|-------------|---------| -| `--user-name ` | Name for agents to use | System username | -| `--communication-language ` | Agent communication language | English | -| `--document-output-language ` | Document output language | English | -| `--output-folder ` | Output folder path | _bmad-output | - -### Other Options - -| Flag | Description | -|------|-------------| -| `-y, --yes` | Accept all defaults and skip prompts | -| `-d, --debug` | Enable debug output for manifest generation | - -## Action Types - -When working with existing installations, use the `--action` flag: - -- `install` - Fresh installation (default for new directories) -- `update` - Modify existing installation (change modules/config) -- `quick-update` - Refresh installation without changing configuration -- `compile-agents` - Recompile agents with customizations only - -Example: - -```bash -npx bmad-method install --action quick-update -``` - -## Module IDs - -Available module IDs for the `--modules` flag: - -### Core Modules -- `bmm` - BMad Method Master -- `bmb` - BMad Builder - -### External Modules -Check the [BMad registry](https://github.com/bmad-code-org) for available external modules. - -## Tool/IDE IDs - -Available tool IDs for the `--tools` flag: - -- `claude-code` - Claude Code CLI -- `cursor` - Cursor IDE -- `windsurf` - Windsurf IDE -- `vscode` - Visual Studio Code -- `jetbrains` - JetBrains IDEs -- And more... - -Run the interactive installer once to see all available tools. - -## Examples - -### Basic Installation - -Install BMM module with Claude Code: - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --modules bmm \ - --tools claude-code \ - --user-name "Development Team" -``` - -### Installation Without Tools - -Install without configuring any tools/IDEs: - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --modules bmm \ - --tools none \ - --user-name "Development Team" -``` - -### Full Installation with Multiple Modules - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --modules bmm,bmb \ - --tools claude-code,cursor \ - --user-name "John Doe" \ - --communication-language English \ - --document-output-language English \ - --output-folder _output -``` - -### Update Existing Installation - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --action update \ - --modules bmm,bmb,custom-module -``` - -### Quick Update (Preserve Settings) - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --action quick-update -``` - -### Installation with Custom Content - -```bash -npx bmad-method install \ - --directory ~/projects/myapp \ - --modules bmm \ - --custom-content ~/my-custom-module,~/another-module \ - --tools claude-code -``` - -### CI/CD Pipeline Installation - -```bash -#!/bin/bash -# install-bmad.sh - -npx bmad-method install \ - --directory "${GITHUB_WORKSPACE}" \ - --modules bmm \ - --tools claude-code \ - --user-name "CI Bot" \ - --communication-language English \ - --document-output-language English \ - --output-folder _bmad-output \ - --yes -``` - -## Environment-Specific Installations - -### Development Environment - -```bash -npx bmad-method install \ - --directory . \ - --modules bmm,bmb \ - --tools claude-code,cursor \ - --user-name "${USER}" -``` - -### Production Environment - -```bash -npx bmad-method install \ - --directory /opt/app \ - --modules bmm \ - --tools claude-code \ - --user-name "Production Team" \ - --output-folder /var/bmad-output -``` - -## Validation and Error Handling - -BMad validates all provided flags: - -- **Directory**: Must be a valid path with write permissions -- **Modules**: Will warn about invalid module IDs (but won't fail) -- **Tools**: Will warn about invalid tool IDs (but won't fail) -- **Custom Content**: Each path must contain a valid `module.yaml` file -- **Action**: Must be one of: install, update, quick-update, compile-agents - -Invalid values will either: -1. Show an error and exit (for critical options like directory) -2. Show a warning and skip (for optional items like custom content) -3. Fall back to interactive prompts (for missing required values) - -## Tips and Best Practices - -1. **Use absolute paths** for `--directory` to avoid ambiguity -2. **Test flags locally** before using in CI/CD pipelines -3. **Combine with `-y`** for truly unattended installations -4. **Check module availability** by running the interactive installer once -5. **Use `--debug`** flag if you encounter issues during installation -6. **Skip tool configuration** with `--tools none` for server/CI environments where IDEs aren't needed -7. **Partial flags are OK** - Omit flags and let BMad prompt for missing values interactively - -## Troubleshooting - -### Installation fails with "Invalid directory" - -Check that: -- The directory path exists or its parent exists -- You have write permissions -- The path is absolute or correctly relative to current directory - -### Module not found - -- Verify the module ID is correct (check available modules in interactive mode) -- External modules may need to be available in the registry - -### Custom content path invalid - -Ensure each custom content path: -- Points to a directory -- Contains a `module.yaml` file in the root -- Has a `code` field in the `module.yaml` - -## Feedback and Issues - -If you encounter any issues with non-interactive installation: - -1. Run with `--debug` flag for detailed output -2. Try the interactive mode to verify the issue -3. Report issues on GitHub: