0
# Medusa CLI
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @medusajs/medusa-cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g @medusajs/medusa-cli` (global installation required)
10
- **Binary Command**: `medusa`
11
- **Node.js Requirements**: Node.js >=16
12

13
**Installation Notes:**
14
- Must be installed globally to access the `medusa` command anywhere
15
- Global installation provides the CLI binary in system PATH
16
- Alternative installation: `yarn global add @medusajs/medusa-cli`
17

18
## Core Imports
19

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

22
```bash
23
# Global installation provides the medusa command
24
npm install -g @medusajs/medusa-cli
25

26
# CLI is then available globally
27
medusa --help
28
medusa new my-store
29
medusa develop
30
```
31

32
For programmatic access within a Medusa project, use:
33

34
```javascript
35
// Access CLI functionality programmatically (within Medusa projects)
36
const { newStarter } = require('@medusajs/medusa-cli/dist/commands/new');
37
const createCli = require('@medusajs/medusa-cli/dist/create-cli');
38
```
39

40
## Basic Usage
41

42
```bash
43
# Create a new Medusa project
44
medusa new my-medusa-store
45

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

49
# Start development server (in Medusa project)
50
cd my-medusa-store
51
medusa develop
52

53
# Run database migrations
54
medusa migrations run
55

56
# Create a user
57
medusa user --email admin@example.com
58
```
59

60
## Architecture
61

62
The Medusa CLI operates in two distinct modes:
63

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

67
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.
68

69
Key architectural components:
70
- **Command Routing**: Automatic detection of Medusa projects via package.json analysis
71
- **Dynamic Loading**: Runtime loading of project-specific commands from local Medusa installation
72
- **Configuration Management**: Persistent storage of user preferences and settings
73
- **Activity Management**: Rich progress reporting with spinners and logging
74
- **Database Integration**: Built-in PostgreSQL database creation and management
75

76
## Capabilities
77

78
### Project Creation
79

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

82
```bash { .api }
83
medusa new [root] [starter] [options]
84

85
# Options:
86
--seed                    # Seed database after setup
87
--y, --useDefaults       # Use default database credentials
88
--skip-db               # Skip database setup
89
--skip-migrations       # Skip running migrations
90
--skip-env             # Skip .env file creation
91
--db-user <string>     # Database username
92
--db-database <string> # Database name
93
--db-pass <string>     # Database password
94
--db-port <number>     # Database port (default: 5432)
95
--db-host <string>     # Database host (default: localhost)
96
```
97

98
[Project Creation](./project-creation.md)
99

100
### Development Server Management
101

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

104
```bash { .api }
105
medusa develop [options]
106
medusa start [options]
107
medusa start-cluster [options]
108

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

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

117
[Development Server](./development-server.md)
118

119
### Database Operations
120

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

123
```bash { .api }
124
medusa migrations <action>
125
# Actions: run | revert | show
126

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

133
[Database Operations](./database-operations.md)
134

135
### User Management
136

137
Create users and manage invitations for Medusa admin access.
138

139
```bash { .api }
140
medusa user [options]
141
# Options:
142
-e, --email <string>        # User's email address
143
-p, --password <string>     # User's password
144
-i, --id <string>          # User's unique identifier
145
--invite                   # Create invitation instead of user
146
```
147

148
[User Management](./user-management.md)
149

150
### Configuration and Utilities
151

152
Global CLI configuration, telemetry settings, and diagnostic utilities.
153

154
```bash { .api }
155
medusa telemetry [options]
156
# Options:
157
--enable     # Enable telemetry collection (default)
158
--disable    # Disable telemetry collection
159
```
160

161
[Configuration](./configuration.md)
162

163
## Global CLI Options
164

165
All commands support these global options:
166

167
```bash { .api }
168
--verbose          # Turn on verbose output
169
--no-color         # Turn off color in output  
170
--no-colors        # Alias for --no-color
171
--json             # Turn on JSON logger
172
--help, -h         # Show help
173
--version, -v      # Show version information
174
```
175

176
## Error Handling
177

178
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.
179

180
## Package Manager Support
181

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

184
## Types
185

186
Core CLI types for programmatic usage:
187

188
```typescript { .api }
189
interface CLIArgs {
190
  root?: string;
191
  starter?: string;
192
  seed?: boolean;
193
  useDefaults?: boolean;
194
  skipDb?: boolean;
195
  skipMigrations?: boolean;
196
  skipEnv?: boolean;
197
  dbUser?: string;
198
  dbDatabase?: string;
199
  dbPass?: string;
200
  dbPort?: number;
201
  dbHost?: string;
202
  verbose?: boolean;
203
  json?: boolean;
204
  help?: boolean;
205
  version?: boolean;
206
}
207

208
interface DatabaseCredentials {
209
  user: string;
210
  database: string;
211
  password: string;
212
  port: number;
213
  host: string;
214
}
215

216
interface ServerOptions {
217
  host?: string;
218
  port?: string | number;
219
  cpus?: number;
220
}
221

222
interface UserOptions {
223
  email?: string;
224
  password?: string;
225
  id?: string;
226
  invite?: boolean;
227
}
228

229
interface TelemetryOptions {
230
  enable?: boolean;
231
  disable?: boolean;
232
}
233
```