{"id":17031,"library":"medusa-dev-cli","title":"Medusa Developer CLI","description":"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.","status":"active","version":"2.13.6","language":"javascript","source_language":"en","source_url":"https://github.com/medusajs/medusa","tags":["javascript","medusa"],"install":[{"cmd":"npm install medusa-dev-cli","lang":"bash","label":"npm"},{"cmd":"yarn add medusa-dev-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add medusa-dev-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for executing TypeScript files in the CLI.","package":"ts-node","optional":false},{"reason":"Enables TypeScript path mapping for module resolution within the CLI.","package":"tsconfig-paths","optional":false}],"imports":[],"quickstart":{"code":"import { exec } from 'node:child_process';\n\nasync function runMedusaDevCommand() {\n  console.log('Running Medusa Dev CLI build command...');\n  // Typically, this CLI is run via `npx medusa-dev <command>`\n  // This example demonstrates programmatic execution, but direct terminal usage is more common.\n  const command = 'npx medusa-dev build';\n\n  return new Promise((resolve, reject) => {\n    exec(command, (error, stdout, stderr) => {\n      if (error) {\n        console.error(`exec error: ${error}`);\n        reject(error);\n        return;\n      }\n      if (stderr) {\n        console.error(`stderr: ${stderr}`);\n      }\n      console.log(`stdout: ${stdout}`);\n      resolve(stdout);\n    });\n  });\n}\n\nrunMedusaDevCommand().catch(console.error);","lang":"typescript","description":"Demonstrates how to invoke a Medusa Developer CLI command ('build') using `npx`."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=2.13.0"},{"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.","message":"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()`.","severity":"breaking","affected_versions":"2.13.2"},{"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.","message":"A regression in v2.13.1 affected total fields selection when listing orders, potentially leading to incorrect data when loading order items with relations.","severity":"breaking","affected_versions":"2.13.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.13.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.12.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2.12.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade `medusa-dev-cli` to v2.13.3 or a newer version to fix the incorrect `req.queryConfig` behavior.","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.","error":"Service with alias \"undefined\" was not found error"},{"fix":"Upgrade `medusa-dev-cli` to v2.12.6 or a later version to resolve known build process regressions.","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.","error":"Build failures related to type generation / link migrations"},{"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.","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.","error":"Zod validation error or type mismatch in @medusajs/framework consumers"}],"ecosystem":"npm","meta_description":null}