or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mddatabase-operations.mddevelopment-server.mdindex.mdproject-creation.mduser-management.md
tile.json

tessl/npm-medusajs--medusa-cli

Command line interface for Medusa Commerce platform with project creation, development server, and database management capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@medusajs/medusa-cli@1.3.x

To install, run

npx @tessl/cli install tessl/npm-medusajs--medusa-cli@1.3.0

index.mddocs/

Medusa CLI

The Medusa CLI is a comprehensive command-line interface for the Medusa Commerce platform. It provides developers with tools for project creation, development server management, database operations, and project lifecycle management. The CLI automatically detects Medusa project contexts and provides appropriate command sets for different scenarios.

Package Information

  • Package Name: @medusajs/medusa-cli
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -g @medusajs/medusa-cli (global installation required)
  • Binary Command: medusa
  • Node.js Requirements: Node.js >=16

Installation Notes:

  • Must be installed globally to access the medusa command anywhere
  • Global installation provides the CLI binary in system PATH
  • Alternative installation: yarn global add @medusajs/medusa-cli

Core Imports

The Medusa CLI is a command-line tool, not a programming library. Access is provided through the global medusa command after installation:

# Global installation provides the medusa command
npm install -g @medusajs/medusa-cli

# CLI is then available globally
medusa --help
medusa new my-store
medusa develop

For programmatic access within a Medusa project, use:

// Access CLI functionality programmatically (within Medusa projects)
const { newStarter } = require('@medusajs/medusa-cli/dist/commands/new');
const createCli = require('@medusajs/medusa-cli/dist/create-cli');

Basic Usage

# Create a new Medusa project
medusa new my-medusa-store

# Create with custom database settings
medusa new my-store --db-user myuser --db-pass mypass

# Start development server (in Medusa project)
cd my-medusa-store
medusa develop

# Run database migrations
medusa migrations run

# Create a user
medusa user --email admin@example.com

Architecture

The Medusa CLI operates in two distinct modes:

  • Global Mode: Available anywhere on the system for project creation and global operations
  • Project Mode: Context-aware commands available only within Medusa projects

The CLI uses dynamic command loading to provide different functionality based on the current working directory. When inside a Medusa project, it dynamically loads additional commands from the local @medusajs/medusa installation.

Key architectural components:

  • Command Routing: Automatic detection of Medusa projects via package.json analysis
  • Dynamic Loading: Runtime loading of project-specific commands from local Medusa installation
  • Configuration Management: Persistent storage of user preferences and settings
  • Activity Management: Rich progress reporting with spinners and logging
  • Database Integration: Built-in PostgreSQL database creation and management

Capabilities

Project Creation

Bootstrap new Medusa projects with automated setup including database creation, environment configuration, and dependency installation.

medusa new [root] [starter] [options]

# Options:
--seed                    # Seed database after setup
--y, --useDefaults       # Use default database credentials
--skip-db               # Skip database setup
--skip-migrations       # Skip running migrations
--skip-env             # Skip .env file creation
--db-user <string>     # Database username
--db-database <string> # Database name
--db-pass <string>     # Database password
--db-port <number>     # Database port (default: 5432)
--db-host <string>     # Database host (default: localhost)

Project Creation

Development Server Management

Start and manage Medusa development and production servers with various configuration options.

medusa develop [options]
medusa start [options]
medusa start-cluster [options]

# Common options for all server commands:
-H, --host <string>      # Set server host (default: localhost)
-p, --port <string>      # Set server port (default: 9000 or PORT env)

# Additional cluster options:
-c, --cpus <number>      # CPU cores for cluster mode (default: all available)

Development Server

Database Operations

Comprehensive database management including migrations, seeding, and schema operations.

medusa migrations <action>
# Actions: run | revert | show

medusa seed --seed-file <path> [options]
# Options:
-f, --seed-file <string>    # Path to seed file (required)
-m, --migrate <boolean>     # Run migrations before seeding (default: true)

Database Operations

User Management

Create users and manage invitations for Medusa admin access.

medusa user [options]
# Options:
-e, --email <string>        # User's email address
-p, --password <string>     # User's password
-i, --id <string>          # User's unique identifier
--invite                   # Create invitation instead of user

User Management

Configuration and Utilities

Global CLI configuration, telemetry settings, and diagnostic utilities.

medusa telemetry [options]
# Options:
--enable     # Enable telemetry collection (default)
--disable    # Disable telemetry collection

Configuration

Global CLI Options

All commands support these global options:

--verbose          # Turn on verbose output
--no-color         # Turn off color in output  
--no-colors        # Alias for --no-color
--json             # Turn on JSON logger
--help, -h         # Show help
--version, -v      # Show version information

Error Handling

The CLI includes comprehensive error handling with structured error messages and helpful suggestions. When commands are mistyped, it provides "did you mean" suggestions. Critical errors are handled through a panic system that logs detailed error information for debugging.

Package Manager Support

The CLI automatically detects and works with both npm and yarn package managers, storing user preferences for consistent behavior across sessions.

Types

Core CLI types for programmatic usage:

interface CLIArgs {
  root?: string;
  starter?: string;
  seed?: boolean;
  useDefaults?: boolean;
  skipDb?: boolean;
  skipMigrations?: boolean;
  skipEnv?: boolean;
  dbUser?: string;
  dbDatabase?: string;
  dbPass?: string;
  dbPort?: number;
  dbHost?: string;
  verbose?: boolean;
  json?: boolean;
  help?: boolean;
  version?: boolean;
}

interface DatabaseCredentials {
  user: string;
  database: string;
  password: string;
  port: number;
  host: string;
}

interface ServerOptions {
  host?: string;
  port?: string | number;
  cpus?: number;
}

interface UserOptions {
  email?: string;
  password?: string;
  id?: string;
  invite?: boolean;
}

interface TelemetryOptions {
  enable?: boolean;
  disable?: boolean;
}