CLI Reference

This document serves as a reference to the Medusa CLI tool including how to install it and what commands are available.

Overview

The Medusa CLI serves as a tool that allows you to perform important commands while developing with Medusa.

To use Medusa, it is required to install the CLI tool as it is used to create a new Medusa backend.

---

How to Install CLI Tool

In your Medusa backend's directory, you can use the Medusa CLI tool using NPX. For example:

npx medusa --help

Alternatively, you can install the CLI tool globally:

• npm
• Yarn
• pnpm

npm install @medusajs/medusa-cli -g
medusa --help

---

## Troubleshooting Installation

<DetailsListSection />

---

## Commands

### new

Create a new Medusa backend.

```bash
medusa new [<backend_name> [<starter_url>]]

yarn global add @medusajs/medusa-cli
medusa --help

---

## Troubleshooting Installation

<DetailsListSection />

---

## Commands

### new

Create a new Medusa backend.

```bash
medusa new [<backend_name> [<starter_url>]]

pnpm add @medusajs/medusa-cli -g
medusa --help

---

## Troubleshooting Installation

<DetailsListSection />

---

## Commands

### new

Create a new Medusa backend.

```bash
medusa new [<backend_name> [<starter_url>]]

Arguments

Name	Description	Default
backend_name	The name of the Medusa backend. It will be used as the name of the directory created.	If not provided, you’ll be prompted to enter it.
starter_url	The URL of the starter to create the backend from.	The default starter is used.

Options

Name	Description
-y, --useDefaults	If the flag is set the command will not interactively collect database credentials.
--skip-db	If the flag is set the command will not attempt to complete the database setup.
--skip-migrations	If the flag is set the command will not attempt to complete the database migration.
--skip-env	If the flag is set the command will not attempt to populate .env.
--db-user <user>	The database user to use for database setup and migrations.
--db-database <database>	The database used for database setup and migrations.
--db-pass <password>	The database password to use for database setup and migrations.
--db-port <port>	The database port to use for database setup and migrations.
--db-host <host>	The database host to use for database setup and migrations.

develop

Start development backend. This command watches files for any changes to rebuild the files and restart the backend.

medusa develop

Options

Name	Description
-H <host>, --host <host>	Set host. Defaults to localhost.
-p <port>, --port <port>	Set port. Defaults to 9000.

start

Start backend in production.

medusa start

Options

Name	Description
-H <host>, --host <host>	Set host. Defaults to localhost.
-p <port>, --port <port>	Set port. Defaults to 9000.

migrations

Perform migration actions to reflect changes on the database, such as running or reverting migrations.

medusa migrations <action>

Arguments

Name	Description	Default
action	The action to perform. Values can be run, show, or revert. run is used to run the migrations; show is used to only show what migrations are available to run; and revert is to undo the last migration.	This argument is required and does not have a default value.

seed

Migrates and populates the database with the provided file.

medusa seed --seed-file=<file_path>

Options

Name	Description
-f=<file_path>, --seed-file=<file_path>	Path to the file where the seed is defined. (required)
-m, --migrate	Flag to indicate if migrations should be run prior to seeding the database. Default is true.

user

Creates a new admin user.

medusa user --email <email> [--password <password>]

Options

Name	Description
-e <email>, --email <email>	The email to create a user with. (required)
-p <password>, --password <password>	The password to use with the user. If not included, the user will not have a password.
-i <id>, --id <id>	The user’s ID. By default it is automatically generated.
--invite	Whether to create an invite instead of a user. When using this option, you don't need to specify a password. If ran successfully, you'll receive the invite token in the output.

start-cluster

Starts the Medusa backend in cluster mode. Running in cluster mode will likely significantly improve performance as the workload and tasks are distributed among all available instances instead of a single one.

medusa start-cluster

Options

Name	Description
-c <number>, --cpus <number>	The number of CPUs that Medusa can consume. By default, Medusa will try to consume all CPUs in cluster mode if this option isn't specified.
-H <host>, --host <host>	Set host. Defaults to localhost.
-p <port>, --port <port>	Set port. Defaults to 9000.

telemetry

Enable or disable the collection of anonymous data usage. If no option is provided, the command will enable the collection of anonymous data usage.

medusa telemetry

Options

Name	Description
--enable	Enable telemetry (default)
--disable	Disable telemetry

---

See Also

• Configure Medusa
• Set up your development environment