n98-magerun2 v10.1.0 (codename Prague) is here, bringing a new way to check database version compatibility before planning your next Magento, Adobe Commerce, or Mage-OS upgrade. This release also adds installation support for the Rust-based Fast DI Compile project and configuration options to control which commands are available in the CLI and through MCP. Alongside those additions, we have improved email testing and fixed several issues affecting repeated customer command calls in MCP sessions.

What’s New

New Command: db:compatibility

Which MySQL or MariaDB version does your application release support? The new db:compatibility command brings that information into your terminal. It detects the installed application and database versions and evaluates their combination against a versioned compatibility dataset bundled with n98-magerun2.

Start with your current installation:

./n98-magerun2.phar db:compatibility

For upgrade planning, supply the application and database versions you want to evaluate. For example, to check a proposed Magento 2.4.9 and MariaDB 11.8 combination:

./n98-magerun2.phar db:compatibility \
  --target-version=2.4.9 \
  --target-db=mariadb \
  --target-db-version=11.8

The command reports whether the combination is supported, unsupported, or unknown, along with the reason. It recognizes Mage-OS as its own product, using Mage-OS version numbers rather than treating the installation as a Magento release.

The bundled requirements data is generated from magento.watch, with exact per-release MySQL and MariaDB requirements. You can also request a live lookup for the current or target application version:

./n98-magerun2.phar db:compatibility --online

When the live lookup succeeds, its data takes precedence over the bundled snapshot. If it fails, the command falls back to the bundled dataset and tells you which source was used.

Default terminal output stays concise. Add -v for the evaluated configuration, dataset metadata, source citations, and database lifecycle information. Use JSON when you need the complete result in a script:

./n98-magerun2.phar db:compatibility -v
./n98-magerun2.phar db:compatibility --format=json

This is a read-only version compatibility check. A supported result does not certify extension, schema, data, or migration compatibility. For automation, note that an unsupported current installation returns a non-zero exit code; an unknown result or an unsupported target configuration alone does not.

Read the db:compatibility documentation.

New Commands: fast-di-compile:install and fast-di-compile:download-binary

Want to try a Rust-based alternative to Magento’s PHP DI compiler? Version 10.1.0 adds two commands for setting up Fast DI Compile, the project by Anton Siniorg (speedupmate).

For the complete installation, run:

./n98-magerun2.phar fast-di-compile:install

The command installs the companion Composer package, enables Spmt_FastDiCompile, runs setup:upgrade, and installs the checksum-verified compiler binary. If your deployment process handles setup:upgrade separately, defer that step with:

./n98-magerun2.phar fast-di-compile:install --no-setup-upgrade

After installation, keep using Magento’s familiar compilation command. You can explicitly select the standard PHP compiler when needed:

bin/magento setup:di:compile
bin/magento setup:di:compile --standard

If you only need the executable, use the download command instead:

./n98-magerun2.phar fast-di-compile:download-binary

It detects Linux or macOS and x64 or arm64, verifies the downloaded assets, and installs the executable at bin/fast-di-compile. The --release and --platform options let you select a specific compiler release and platform. Downloading the binary alone does not install or enable the companion Magento module.

Read the installation documentation and binary download documentation.

Control Command Availability in CLI and MCP

You can now disable individual commands or entire namespaces through configuration. Both global and MCP-specific exclusions support wildcard patterns.

For example, add this to your Magento project’s app/etc/n98-magerun2.yaml to disable database dump and import commands globally:

commands:
  disabled:
    - db:dump
    - db:import

Globally disabled commands are unavailable in the CLI and as MCP tools. To keep commands available for terminal use while excluding them from your AI assistant’s MCP tools, use the MCP-specific configuration instead:

commands:
  N98\Magento\Command\Mcp\Server\StartCommand:
    disabled:
      - 'db:*'
      - '@unsafe'

This example excludes all database commands and the predefined unsafe command group from MCP. The MCP-specific list uses canonical CLI command names, such as db:dump, rather than MCP tool names such as db_dump. Disabled tools stay excluded even when selected with --include.

Configuration changes apply on the next CLI invocation. Restart an already-running MCP server to refresh its tool list.

Read the command disabling documentation.

Improvements

• sys:email:test: You can now pass the recipient directly as a positional argument. The existing --to option remains available, so existing scripts continue to work.
• Database compatibility output: Standard text output focuses on the verdict and reason, with detailed information available through -v. JSON output always includes the complete result. Live lookups use --online; the development option --dataset-url has been removed.
• Contributor workflows: Shared /issue and /pr slash commands help contributors using Claude Code or OpenCode file issues and pull requests against the project. Documentation also covers MCP usage in DDEV and AI-assisted contributions.
• Dependencies: Updated runtime and documentation dependencies, including fixes for npm security advisories.

The shorter email test syntax looks like this:

./n98-magerun2.phar sys:email:test [email protected]

Bug Fixes

• MCP argument handling: Multiple positional arguments now bind in declaration order, including quoted values and trailing arrays. Single scalar arguments retain their verbatim input (#2178).
• customer:change-password: Missing or empty passwords are rejected without changing the stored password hash (#2173, #2178).
• Repeated customer operations: customer:change-password and customer:add-address preserve the previous Magento area, improving reliability across repeated calls (#2174, #2175, #2178).
• customer:info: Attribute-rendering errors are caught, and fallback output remains consistent across repeated calls (#2176, #2178).
• Interactive cron selection: The job selector has a limited height to keep long job lists manageable in the terminal.
• Compatibility data: The bundled dataset now comes from actual per-release database requirements rather than hand-authored, unverified entries (#2141).

Full Changelog

Additions

• Add: fast-di-compile:download-binary command to download a checksum-verified Rust DI compiler binary for the selected release and platform.
• Add: fast-di-compile:install command to install and enable the companion Magento module and verified compiler binary, with an optional --no-setup-upgrade flag.
• Add: disable commands globally or only as MCP tools through configuration, with wildcard pattern support.
• Add: db:compatibility command to assess Magento/Adobe Commerce and MySQL/MariaDB version compatibility against a versioned dataset (./res/db-compatibility.json), with --target-version, --target-db, --target-db-version and --format=json support (#2141).
• Add: db:compatibility detects Mage-OS installations as their own product (with their own version numbering) instead of evaluating them as plain Magento (#2141).
• Add: db:compatibility --online checks the current/target application version live against magento.watch instead of relying solely on the bundled dataset (#2141).
• Add: /issue and /pr slash commands for Claude Code and OpenCode to file issues and pull requests against the project.

Improvements and Changes

• Imp: sys:email:test accepts the recipient as a positional argument while retaining the --to option.
• Change: db:compatibility standard output trimmed to the essentials (verdict and reason); the full evaluated-configuration and database lifecycle tables, dataset metadata, finding IDs, and source citations now require -v (--format=json is unaffected and always complete) (#2141).
• Remove: db:compatibility --dataset-url — there is no remote endpoint to point it at; use --online for live data instead (#2141).

Fixes

• Fix: bind multiple MCP positional arguments in declaration order, supporting quoted values and trailing arrays while preserving verbatim input for single scalar arguments (#2178).
• Fix: customer:change-password reject missing or empty passwords without changing the stored password hash (#2173, #2178).
• Fix: preserve the previous area during repeated customer:change-password and customer:add-address calls (#2174, #2175, #2178).
• Fix: customer:info catch attribute-rendering errors and consistently render fallback output on repeated calls (#2176, #2178).
• Fix: limit the interactive cron job selector height.
• Fix: db:compatibility‘s bundled dataset regenerated from real, per-release MySQL/MariaDB requirements data (via a new scripts/import-db-compatibility-dataset.php importer sourced from magento.watch) instead of hand-authored, unverified entries (#2141).

Tests

• Test: add regression coverage for MCP argument binding, repeated customer command calls, rejected passwords, area preservation, and attribute-rendering failures (#2178).
• Test: tolerate temporary GitHub outages in BATS tests.

Documentation

• Docs: clarify MCP positional argument handling and customer password requirements (#2178).
• Docs: document fast DI compiler commands, positional email recipients, global and MCP command disabling, MCP usage in DDEV, and AI-assisted contributor workflows.

Maintenance

• Chore: allow committing shared .claude project config (commands, skills).
• Chore: configure local development tooling.

Build

• Build: build.sh refreshes and schema-validates the db:compatibility dataset before packaging a release, with a --skip-dataset-fetch opt-out (#2141).
• Build: update mcp/sdk to 0.8.1.
• Build: update twig/twig to 3.30.0 and rmccue/requests to 2.0.20.
• Build: update phpstan/phpstan to 2.2.16 and friendsofphp/php-cs-fixer to 3.95.27.
• Build: update github-community-projects/contributors to 2.0.20 (#2136).
• Build: update npm/yarn documentation dependencies, including postcss-selector-parser, and resolve npm security advisories.

How to Update

As always, the easiest way to update is via the built-in self-update command:

./n98-magerun2.phar self-update

Try db:compatibility against your current environment or the versions you are planning to upgrade to, and explore the new compiler installation commands. We would love to hear how these additions fit into your workflow—leave a comment below or share your feedback in GitHub Discussions. If you find a bug, please open an issue.