0
# User Management
1

2
The Medusa CLI provides user management capabilities for creating admin users and generating invitations for Medusa Commerce projects. This command is only available within Medusa project directories and integrates with the local Medusa installation's user management system.
3

4
## Capabilities
5

6
### User Creation
7

8
Create admin users or generate invitation tokens for Medusa admin access.
9

10
```bash { .api }
11
medusa user [options]
12
```
13

14
**Options:**
15
- `-e, --email <string>`: User's email address
16
- `-p, --password <string>`: User's password
17
- `-i, --id <string>`: User's unique identifier
18
- `--invite`: Create invitation instead of user (returns invite token)
19

20
**Usage Examples:**
21

22
```bash
23
# Interactive user creation (prompts for details)
24
medusa user
25

26
# Create user with email and password
27
medusa user --email admin@example.com --password secretpass
28

29
# Create user with custom ID
30
medusa user --email admin@store.com --password mypass --id admin-001
31

32
# Generate invitation token instead of creating user
33
medusa user --email newadmin@store.com --invite
34

35
# Create invitation with specific email
36
medusa user --invite --email invited@example.com
37
```
38

39
## User Creation Modes
40

41
### Direct User Creation
42

43
Creates a new admin user directly in the database:
44

45
**Standard User Creation:**
46
- Creates user account with provided credentials
47
- Stores encrypted password in database
48
- Assigns appropriate admin permissions
49
- Provides confirmation of successful creation
50

51
**Required Information:**
52
- Email address (for login identification)
53
- Password (securely hashed before storage)
54
- Optional custom user ID (auto-generated if not provided)
55

56
**Database Integration:**
57
- Uses project's configured database connection
58
- Integrates with Medusa's user management system
59
- Follows Medusa's authentication and authorization patterns
60

61
### Invitation Generation
62

63
Creates invitation tokens instead of direct user accounts:
64

65
**Invitation Token Creation:**
66
- Generates secure invitation token
67
- Associates token with specified email address
68
- Sets expiration time for invitation validity
69
- Returns token for distribution to invited user
70

71
**Invitation Workflow:**
72
1. CLI generates secure invitation token
73
2. Token is stored in database with expiration
74
3. Token is returned to administrator
75
4. Administrator shares token with invited user
76
5. Invited user uses token to complete registration
77

78
**Token Characteristics:**
79
- Cryptographically secure random generation
80
- Time-limited validity (expires after specified period)
81
- Single-use tokens (invalidated after registration)
82
- Associated with specific email address
83

84
## Interactive User Creation
85

86
When no options are provided, the command enters interactive mode:
87

88
**Interactive Prompts:**
89
1. **Email Address**: Prompts for user's email address with validation
90
2. **Password**: Secure password input (hidden from terminal display)
91
3. **User ID**: Optional custom identifier (auto-generated if skipped)
92
4. **Creation Type**: Choose between direct user creation or invitation generation
93

94
**Input Validation:**
95
- Email format validation
96
- Password strength requirements (if configured)
97
- User ID uniqueness checking
98
- Duplicate email detection
99

100
## Security Considerations
101

102
### Password Handling
103

104
The CLI implements secure password management:
105

106
**Password Security:**
107
- Passwords are securely hashed before database storage
108
- Uses Medusa's configured password hashing algorithm
109
- No plaintext password storage or logging
110
- Secure input handling (hidden terminal input)
111

112
**Password Requirements:**
113
- Follows project's configured password policies
114
- Minimum length requirements (if specified)
115
- Complexity requirements (if configured)
116
- Integration with Medusa's authentication system
117

118
### Access Control
119

120
User creation respects Medusa's security model:
121

122
**Permission Assignment:**
123
- New users receive appropriate admin permissions
124
- Role-based access control integration
125
- Secure authentication token generation
126
- Integration with existing permission systems
127

128
**Database Security:**
129
- Secure database connection using project configuration
130
- Transaction-based operations for data consistency
131
- Proper error handling to prevent information disclosure
132
- Audit trail for user creation activities
133

134
## Error Handling
135

136
### Validation Errors
137

138
The user management system handles various validation scenarios:
139

140
**Email Validation:**
141
- Format checking for valid email addresses
142
- Duplicate email detection and prevention
143
- Domain validation (if configured)
144
- Integration with project's email validation rules
145

146
**User Creation Errors:**
147
- Database connection failures
148
- Duplicate user prevention
149
- Invalid parameter handling
150
- Permission and access control errors
151

152
### Recovery and Feedback
153

154
**Error Reporting:**
155
- Clear error messages for failed operations
156
- Specific guidance for resolution steps
157
- Detailed logging for debugging purposes
158
- Graceful handling of system limitations
159

160
**Success Confirmation:**
161
- Confirmation messages for successful user creation
162
- Invitation token display for invitation mode
163
- User details summary (excluding sensitive information)
164
- Next steps guidance for new users
165

166
## Command Integration
167

168
### Project Context Requirements
169

170
User management commands require proper project context:
171

172
**Medusa Project Detection:**
173
- Must be run within valid Medusa project directory
174
- Requires local @medusajs/medusa installation
175
- Uses project's database and configuration settings
176
- Integrates with project's authentication system
177

178
**Configuration Access:**
179
- Reads database configuration from project settings
180
- Uses environment variables and config files
181
- Respects project's authentication policies
182
- Maintains consistency with project's user model
183

184
### Command Proxying
185

186
User commands are proxied to the local Medusa installation:
187

188
**Dynamic Command Loading:**
189
- Commands resolved from local Medusa installation
190
- Version compatibility with project's Medusa version
191
- Automatic fallback to help if commands unavailable
192
- Full integration with Medusa's user management API
193

194
**Argument Processing:**
195
- All CLI options passed to underlying Medusa commands
196
- Project context automatically included
197
- Maintains compatibility with Medusa's native user tools
198
- Proper handling of interactive and non-interactive modes