Medusa Developer CLI

2.13.6 · active · verified Wed Apr 22

medusa-dev-cli is a command-line interface (CLI) tool designed to provide development-specific helpers for contributors working on the Medusa e-commerce platform. It is part of the larger Medusa monorepo and is primarily intended for tasks like building, watching, and other development workflows within the Medusa ecosystem, rather than for direct programmatic library consumption in end-user projects. The current stable version is 2.13.6, with frequent patch and minor releases aligning with Medusa's rapid development cycle. Its key differentiator is its specific focus on developer experience for core Medusa contributors, providing specialized commands not typically exposed in the main `medusa-cli` for merchant projects. It relies on `ts-node` and `tsconfig-paths` for its execution environment.

Common errors

```
Service with alias "undefined" was not found error
```
cause A regression in `medusa-dev-cli` v2.13.2 caused `req.queryConfig` to include `entity: undefined`, which, when spread into `query.graph()`, overwrote the intended entity.

fix Upgrade `medusa-dev-cli` to v2.13.3 or a newer version to fix the incorrect `req.queryConfig` behavior.
```
Build failures related to type generation / link migrations
```
cause A regression in `medusa-dev-cli` v2.12.5 (and possibly earlier related versions) introduced issues in the build process concerning type generation and link migrations.

fix Upgrade `medusa-dev-cli` to v2.12.6 or a later version to resolve known build process regressions.
```
Zod validation error or type mismatch in @medusajs/framework consumers
```
cause The v2.13.0 release restructured Zod dependencies, adding `zod` directly to `@medusajs/framework`, which could conflict with existing `zod` versions in a project or introduce unexpected type behaviors.

fix Review your project's `zod` dependencies and ensure compatibility with the version now integrated into `@medusajs/framework`. Update `zod` if necessary, or check for explicit version locks causing conflicts.

Warnings

breaking The v2.13.0 release introduced a breaking change with 'Zod dependency restructuring', adding `zod` as a dependency of `@medusajs/framework`. This might affect projects that directly managed `zod` versions or relied on its absence in `@medusajs/framework`.
Fix: Ensure `zod` is a compatible dependency in your project if you're directly using `@medusajs/framework` or related packages. Review your `package.json` and `package-lock.json` for potential conflicts.
breaking A regression in v2.13.2 caused `req.queryConfig` to incorrectly include `entity: undefined`, leading to 'Service with alias "undefined" was not found error' when spreading `req.queryConfig` into `query.graph()`.
Fix: Immediately upgrade to v2.13.3 or higher to resolve this regression. Avoid using `medusa-dev-cli` v2.13.2 in production or development environments.
breaking A regression in v2.13.1 affected total fields selection when listing orders, potentially leading to incorrect data when loading order items with relations.
Fix: Upgrade to v2.13.2 or higher to fix the regression in order listing totals. Re-test any custom order listing logic after upgrade.
gotcha Version 2.13.6 includes an update for MikroORM dependencies to v6.6.12 due to recent security vulnerabilities. While Medusa's core API routes are typically guarded with Zod validation, custom API routes *not* properly guarded may be impacted.
Fix: Ensure all custom API routes in your Medusa project are properly guarded with validation (e.g., Zod validation) to prevent potential security vulnerabilities. Review any direct MikroORM usage outside of Medusa's core patterns.
gotcha Translations features, introduced in v2.12.3 and expanded in v2.12.4, are explicitly marked as 'experimental'. This implies their API or behavior may change in future releases.
Fix: When using experimental translation features, be prepared for potential breaking changes in subsequent releases. Refer to the latest Medusa documentation for updates on the translation API.
gotcha Version 2.12.5 fixed a regression in the build process related to type generation, which could cause build failures under certain conditions due to issues with link migrations.
Fix: Ensure you are using v2.12.6 or a later version to avoid build failures related to type generation. If experiencing build issues on older versions, upgrading is the primary recommended fix.

Install

npm install medusa-dev-cli npm
yarn add medusa-dev-cli yarn
pnpm add medusa-dev-cli pnpm

Quickstart

Demonstrates how to invoke a Medusa Developer CLI command ('build') using `npx`.

import { exec } from 'node:child_process';

async function runMedusaDevCommand() {
  console.log('Running Medusa Dev CLI build command...');
  // Typically, this CLI is run via `npx medusa-dev <command>`
  // This example demonstrates programmatic execution, but direct terminal usage is more common.
  const command = 'npx medusa-dev build';

  return new Promise((resolve, reject) => {
    exec(command, (error, stdout, stderr) => {
      if (error) {
        console.error(`exec error: ${error}`);
        reject(error);
        return;
      }
      if (stderr) {
        console.error(`stderr: ${stderr}`);
      }
      console.log(`stdout: ${stdout}`);
      resolve(stdout);
    });
  });
}

runMedusaDevCommand().catch(console.error);

view raw JSON →