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

To install the CLI tool, run the following command in your terminal:

• npm
• Yarn
• pnpm

npm install @medusajs/medusa-cli -g

Report Incorrect CodeCopy to Clipboard

yarn global add @medusajs/medusa-cli

Report Incorrect CodeCopy to Clipboard

pnpm add @medusajs/medusa-cli -g

Report Incorrect CodeCopy to Clipboard

If you run into any errors while installing the CLI tool, check out the troubleshooting section.

The CLI tool is then available under the medusaCopy to Clipboard command. You can see all commands and options with the following command:

medusa --help

Report Incorrect CodeCopy to Clipboard

---

Troubleshooting Installation

NPM Error: EACCES Permissions Errors

If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory.

You can check out more information in NPM’s documentation.

Powershell Error: command not found: medusa

If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error:

command not found: medusa

Copy to Clipboard

Try closing your Powershell window and opening a new one.

Yarn Error: command not found: medusa

If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error:

command not found: medusa

Copy to Clipboard

You have to add Yarn’s install location to the PATH variable:

• MacOS / Linux
• Windows

export PATH="$(yarn global bin):$PATH"

Report Incorrect CodeCopy to Clipboard

# MAKE SURE TO INCLUDE %path%
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
# YOURUSERNAME is your account username

Report Incorrect CodeCopy to Clipboard

You can learn more in Yarn’s documentation.

---

Common Options

The following options can be used with all available commands.

--help

Learn more about what you can do with the CLI tool or with a specific command.

Alias: -hCopy to Clipboard

medusa new --help

Report Incorrect CodeCopy to Clipboard

--verbose

Turn on verbose output for detailed logs.

Default: falseCopy to Clipboard

medusa new my-backend --verbose

Report Incorrect CodeCopy to Clipboard

--no-color

Turn off colors in the output.

Alias: --no-colorsCopy to Clipboard

Default: falseCopy to Clipboard

medusa new my-backend --no-color

Report Incorrect CodeCopy to Clipboard

--json

Turn on JSON logger.

Default: falseCopy to Clipboard

medusa new my-backend --json

Report Incorrect CodeCopy to Clipboard

--version

If used inside a Medusa project, the version of the Medusa CLI and Medusa project is shown. Otherwise, the version of the Medusa CLI is shown.

Alias: -vCopy to Clipboard

medusa --version

Report Incorrect CodeCopy to Clipboard

---

Available Commands

new

Create a new Medusa backend.

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

Report Incorrect CodeCopy to Clipboard

Arguments

Name	Description	Default
backend_nameCopy to Clipboard	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_urlCopy to Clipboard	The URL of the starter to create the backend from.	The default starter is used.

Options

Name	Description
-yCopy to Clipboard, --useDefaultsCopy to Clipboard	If the flag is set the command will not interactively collect database credentials.
--skip-dbCopy to Clipboard	If the flag is set the command will not attempt to complete the database setup.
--skip-migrationsCopy to Clipboard	If the flag is set the command will not attempt to complete the database migration.
--skip-envCopy to Clipboard	If the flag is set the command will not attempt to populate .env.
--db-userCopy to Clipboard	The database user to use for database setup and migrations.
--db-databaseCopy to Clipboard	The database used for database setup and migrations.
--db-passCopy to Clipboard	The database password to use for database setup and migrations.
--db-portCopy to Clipboard	The database port to use for database setup and migrations.
--db-hostCopy to Clipboard	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

Report Incorrect CodeCopy to Clipboard

Options

Name	Description
-HCopy to Clipboard, --hostCopy to Clipboard	Set host. Defaults to localhost.
-pCopy to Clipboard, --portCopy to Clipboard	Set port. Defaults to 9000.

start

Start development backend. This command does not watch for file changes or restart the backend.

medusa start

Report Incorrect CodeCopy to Clipboard

Options

Name	Description
-HCopy to Clipboard, --hostCopy to Clipboard	Set host. Defaults to localhost.
-pCopy to Clipboard, --portCopy to Clipboard	Set port. Defaults to 9000.

migrations

Migrate the database to the most recent version.

medusa migrations <action>

Report Incorrect CodeCopy to Clipboard

Arguments

Name	Description	Default
actionCopy to Clipboard	The action to perform. Values can be runCopy to Clipboard, showCopy to Clipboard, or revertCopy to Clipboard. runCopy to Clipboard is used to run the migrations; showCopy to Clipboard is used to only show what migrations are available to run; and revertCopy to Clipboard 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>

Report Incorrect CodeCopy to Clipboard

Options

Name	Description
-fCopy to Clipboard, --seed-fileCopy to Clipboard	Path to the file where the seed is defined. (required)
-mCopy to Clipboard, --migrateCopy to Clipboard	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>]

Report Incorrect CodeCopy to Clipboard

Options

Name	Description
-e <email>Copy to Clipboard, --email <email>Copy to Clipboard	The email to create a user with. (required)
-p <password>Copy to Clipboard, --password <password>Copy to Clipboard	The password to use with the user. If not included, the user will not have a password.
-i <id>Copy to Clipboard, --id <id>Copy to Clipboard	The user’s ID. By default it is automatically generated.
--inviteCopy to Clipboard	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.

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

Report Incorrect CodeCopy to Clipboard

Options

Name	Description
--enableCopy to Clipboard	Enable telemetry (default)
--disableCopy to Clipboard	Disable telemetry

---

See Also

• Configure Medusa
• Set up your development environment