brXM Upgrade Tool

AI-powered CLI tool for Bloomreach Experience Manager (brXM) version upgrades.

Overview

The brXM Upgrade Tool simplifies version upgrades by:

• Analyzing your project to understand its structure and customizations
• Planning upgrades based on version-specific manifests
• Executing transformations with AI assistance
• Guiding you through manual steps when needed

Installation

Via npx (recommended)

Run from any brXM project directory:

npx @bloomreach/brxm-upgrade discover
npx @bloomreach/brxm-upgrade plan

To force a fresh fetch (bypass npx cache):

npx --yes @bloomreach/brxm-upgrade@latest <command>

MCP Server (Claude Code integration)

Add to your .mcp.json:

{
  "mcpServers": {
    "brxm-upgrade": {
      "command": "npx",
      "args": ["-p", "@bloomreach/brxm-upgrade", "brxm-upgrade-mcp"]
    }
  }
}

Quick Start

# Navigate to your brXM project root
cd /path/to/your/brxm-project

# Check tool information
brxm-upgrade info

# Analyze your project
brxm-upgrade discover

# Generate upgrade plan
brxm-upgrade plan --to 16.3

# Execute the upgrade
brxm-upgrade execute

Configuration

Interactive setup (recommended)

Run the configure command to set up your AI provider interactively. It writes a .brxmrc file in the current directory:

npx @bloomreach/brxm-upgrade configure

The wizard prompts for provider, model, API key, and an optional base URL (for LiteLLM or other OpenAI-compatible proxies).

Manual .brxmrc

Create a .brxmrc file in your project root or home directory:

ai:
  provider: anthropic
  model: claude-sonnet-4-6
  apiKeyEnv: ANTHROPIC_API_KEY  # recommended: read key from this env var
  # apiKey: sk-ant-...          # alternative: stored in plaintext — do NOT commit .brxmrc

upgrade:
  source: bundled             # 'bundled' (default), 'local', or 'url'

output:
  verbose: false
  color: true
  exportPath: ./.brxm-upgrade

Security: prefer apiKeyEnv so your key stays out of the file. If you do set a literal apiKey, never commit .brxmrc — it is git-ignored by default for this reason.

See fixtures/.brxmrc.example.yaml for a complete example.

Custom base URL (proxies and self-hosted models)

If your organisation routes AI calls through an OpenAI-compatible proxy (e.g. LiteLLM) or a self-hosted model, set baseUrl in .brxmrc or supply it when prompted by configure:

ai:
  provider: anthropic          # or openai / google, depending on your proxy config
  model: claude-sonnet-4-6
  apiKey: your-proxy-key
  baseUrl: https://litellm.example.com/v1

For the Anthropic provider the /v1 suffix is appended automatically if omitted, so both https://litellm.example.com and https://litellm.example.com/v1 work. For OpenAI and Google the URL is passed through as-is.

API key lookup order

1. ai.apiKey in .brxmrc (explicit, wins if non-empty)
2. Environment variable named by ai.apiKeyEnv in .brxmrc, or the provider default (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_AI_API_KEY)

Supported AI Providers

The tool supports multiple AI providers (BYOK - Bring Your Own Key):

| Provider | Environment Variable | Default Model | |----------|---------------------|---------------| | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 | | OpenAI | OPENAI_API_KEY | gpt-4o | | Google | GOOGLE_AI_API_KEY | gemini-2.5-pro |

Manifests and supported upgrade paths

Manifests are the structured descriptions of every change required to move from one brXM version to the next. The tool requires manifests for both the source and target major version — if either is absent the upgrade is blocked with a clear error.

Download the latest manifest catalog with:

npx @bloomreach/brxm-upgrade setup-manifests

Run brxm-upgrade info to see which version ranges are currently covered by the installed catalog.

Cross-major upgrades (e.g. 15.x → 16.x) require manifests that span both majors. The tool will exit early with a descriptive error if the catalog does not cover the requested upgrade path.

Commands

| Command | Description | |---------|-------------| | configure | Interactively set up AI provider, model, API key, and base URL | | info | Display tool and configuration status | | setup-manifests | Download the brXM upgrade manifest catalog | | discover | Analyze your project structure and detect the current brXM version | | plan | Generate an upgrade plan from the manifest catalog | | execute | Execute the upgrade plan step by step | | log-change | Create manifest entries from change documents (maintainers) | | finalize | Promote unreleased manifest entries to a versioned release (maintainers) | | export | Export the upgrade plan as markdown for use with an AI agent |

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

License

Apache-2.0 - See LICENSE file for details.