mage-remote-run with JSON Body Support and Other New Features

Two releases in one day — that happens when features are ready. On June 17, 2026, I released v1.9.0 and v1.10.0 of mage-remote-run. The highlight in v1.9: Virtual Commands now support JSON request bodies — making POST and PUT requests against the Magento REST API possible without writing your own JavaScript code. v1.10 brings cleaner plugin infrastructure: incompatible plugins are now detected during loading and rejected with a clear error message.

v1.9.0: Virtual Commands with JSON Body, Choices, and Interactive Prompts

Virtual Commands have been a central extensibility feature since v1.4: define REST requests through configuration, without having to write JavaScript. Until now, they were limited to GET requests. That is now history.

JSON Body Templates

With body in the command definition, POST and PUT requests can be sent directly from the configuration. The body is a JSON template. Options are embedded as placeholders and substituted at runtime.

{
  "name": "customer update-email",
  "method": "PUT",
  "endpoint": "/V1/customers/:id",
  "description": "Update customer email address",
  "body": {
    "customer": {
      "id": ":id",
      "email": ":email"
    }
  },
  "options": {
    "id": {
      "type": "string",
      "required": true,
      "description": "Customer ID"
    },
    "email": {
      "type": "string",
      "required": true,
      "description": "New email address"
    }
  }
}

mage-remote-run customer update-email --id 42 --email new@example.com

This opens up the entire Magento REST API to Virtual Commands — not just read operations, but write workflows as well, without custom plugin code.

You can find the full documentation here: mage-remote-run.muench.dev/extensibility/virtual-commands

Choices for Option Definitions

Options can now have predefined choices. This makes commands more user-friendly and prevents invalid input:

"options": {
  "status": {
    "type": "string",
    "required": true,
    "description": "Order status",
    "choices": ["pending", "processing", "complete", "canceled"]
  }
}

In interactive mode, choices appear as a selection menu. Via the CLI, invalid values are rejected immediately.

Interactive Prompts for Missing Required Options

Virtual Commands now prompt interactively for missing required options instead of aborting with an error message. The behavior depends on the context: a prompt appears in the terminal; in CI/CD pipelines, the error is reported as before. Where possible, variables already defined by default by CI/CD systems such as Gitlab-CI or Github Actions (such as CI=1) are detected automatically, so interactive mode cannot block the pipeline.

For pipelines, interactive mode can also be disabled explicitly:

NON_INTERACTIVE=1 mage-remote-run my-command
# alternativ:
NONINTERACTIVE=1 mage-remote-run my-command

Both environment variables are accepted as aliases, in the spirit of Homebrew conventions for shell scripting.

Other Changes in v1.9

• Performance: Config I/O now runs fully asynchronously (fs.promises instead of synchronous fs) — noticeable when switching profiles frequently
• Performance: findRegisteredPluginIndex uses Promise.all for parallel checks
• Fix: Swallowed errors in catch blocks have been fixed — errors are now visible instead of silently ignored
• Refactoring: Duplicated filter-matching logic has been extracted into parseFilterOption
• Deps: axios, zod, inquirer, and @modelcontextprotocol/sdk updated to current versions

v1.10.0: Plugin Compatibility Checks via peerDependencies

Plugins have declared a peerDependency on mage-remote-run since v1.6. Starting with v1.10, it is actually evaluated during loading.

If a plugin requires a version of mage-remote-run that does not match the installed version, loading aborts with a clear error message — rather than inexplicable runtime behavior.

This is the usual principle: explicitly bad is better than silently wrong. Anyone developing or using plugins declares the peerDependency in the plugin's package.json:

{
  "name": "my-mage-remote-run-plugin",
  "peerDependencies": {
    "mage-remote-run": ">=1.10.0"
  }
}

The check runs during plugin loading — before commands are registered. Incompatible plugins are skipped and the error is logged.

Update

npm update -g mage-remote-run

Or straight to the current version:

npm install -g mage-remote-run@latest

Feedback and bug reports via GitHub Issues, as always. If you use Virtual Commands in production or develop plugins... I would love to hear about your experiences.