User Management

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.

Capabilities

User Creation

Create admin users or generate invitation tokens 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 (returns invite token)

Usage Examples:

# Interactive user creation (prompts for details)
medusa user

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

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

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

# Create invitation with specific email
medusa user --invite --email invited@example.com

User Creation Modes

Direct User Creation

Creates a new admin user directly in the database:

Standard User Creation:

• Creates user account with provided credentials
• Stores encrypted password in database
• Assigns appropriate admin permissions
• Provides confirmation of successful creation

Required Information:

• Email address (for login identification)
• Password (securely hashed before storage)
• Optional custom user ID (auto-generated if not provided)

Database Integration:

• Uses project's configured database connection
• Integrates with Medusa's user management system
• Follows Medusa's authentication and authorization patterns

Invitation Generation

Creates invitation tokens instead of direct user accounts:

Invitation Token Creation:

• Generates secure invitation token
• Associates token with specified email address
• Sets expiration time for invitation validity
• Returns token for distribution to invited user

Invitation Workflow:

1. CLI generates secure invitation token
2. Token is stored in database with expiration
3. Token is returned to administrator
4. Administrator shares token with invited user
5. Invited user uses token to complete registration

Token Characteristics:

• Cryptographically secure random generation
• Time-limited validity (expires after specified period)
• Single-use tokens (invalidated after registration)
• Associated with specific email address

Interactive User Creation

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

Interactive Prompts:

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

Input Validation:

• Email format validation
• Password strength requirements (if configured)
• User ID uniqueness checking
• Duplicate email detection

Security Considerations

Password Handling

The CLI implements secure password management:

Password Security:

• Passwords are securely hashed before database storage
• Uses Medusa's configured password hashing algorithm
• No plaintext password storage or logging
• Secure input handling (hidden terminal input)

Password Requirements:

• Follows project's configured password policies
• Minimum length requirements (if specified)
• Complexity requirements (if configured)
• Integration with Medusa's authentication system

Access Control

User creation respects Medusa's security model:

Permission Assignment:

• New users receive appropriate admin permissions
• Role-based access control integration
• Secure authentication token generation
• Integration with existing permission systems

Database Security:

• Secure database connection using project configuration
• Transaction-based operations for data consistency
• Proper error handling to prevent information disclosure
• Audit trail for user creation activities

Error Handling

Validation Errors

The user management system handles various validation scenarios:

Email Validation:

• Format checking for valid email addresses
• Duplicate email detection and prevention
• Domain validation (if configured)
• Integration with project's email validation rules

User Creation Errors:

• Database connection failures
• Duplicate user prevention
• Invalid parameter handling
• Permission and access control errors

Recovery and Feedback

Error Reporting:

• Clear error messages for failed operations
• Specific guidance for resolution steps
• Detailed logging for debugging purposes
• Graceful handling of system limitations

Success Confirmation:

• Confirmation messages for successful user creation
• Invitation token display for invitation mode
• User details summary (excluding sensitive information)
• Next steps guidance for new users

Command Integration

Project Context Requirements

User management commands require proper project context:

Medusa Project Detection:

• Must be run within valid Medusa project directory
• Requires local @medusajs/medusa installation
• Uses project's database and configuration settings
• Integrates with project's authentication system

Configuration Access:

• Reads database configuration from project settings
• Uses environment variables and config files
• Respects project's authentication policies
• Maintains consistency with project's user model

Command Proxying

User commands are proxied to the local Medusa installation:

Dynamic Command Loading:

• Commands resolved from local Medusa installation
• Version compatibility with project's Medusa version
• Automatic fallback to help if commands unavailable
• Full integration with Medusa's user management API

Argument Processing:

• All CLI options passed to underlying Medusa commands
• Project context automatically included
• Maintains compatibility with Medusa's native user tools
• Proper handling of interactive and non-interactive modes