Skip to main content

​
medusa user

Create an admin user or invitation for your Medusa application.

​
Usage

medusa user

​
Description

The medusa user command creates a new admin user or generates an invitation token for your Medusa application. This is useful for:
  • Creating the first admin user for a new installation
  • Adding additional admin users
  • Generating invitation links for new administrators
When creating a user, the command:
  1. Creates a user record in the database
  2. Registers authentication credentials with the email/password provider
  3. Assigns roles (including super admin role if RBAC is enabled)
  4. Links the authentication identity to the user

​
Options

​
-e, --email <email>

The email address for the user. 
medusa user --email [email protected]
  • Type: string
  • Required: Yes (prompted if not provided)

​
-p, --password <password>

The password for the user. 
medusa user --email [email protected] --password SecurePass123
  • Type: string
  • Required: Yes for user creation (prompted if not provided)
  • Not used when --invite flag is set

​
-i, --id <id>

Optional user ID to assign. 
medusa user --email [email protected] --id user_123
  • Type: string
  • Default: Auto-generated

​
--invite

Create an invitation instead of a user directly. 
medusa user --email [email protected] --invite
  • Type: boolean
  • Default: false
When this flag is set:
  • An invitation is created instead of a user
  • No password is required
  • An invite token is returned
  • The user can complete registration via the admin dashboard

​
Interactive Mode

If you run the command without options, you’ll be prompted for the required information: 
medusa user
You’ll see prompts like: 
? Email: [email protected]
? Password: ••••••••••••

​
Examples

​
Create a User

Create a new admin user with email and password: 
medusa user --email [email protected] --password SecurePass123
Output: 
info: Assigning super admin role to user.
info: User created successfully. Super admin role assigned.

​
Create a User Interactively

Run without arguments to be prompted: 
medusa user
Interactive prompts: 
? Email: [email protected]
? Password: ••••••••••••
info: Assigning super admin role to user.
info: User created successfully. Super admin role assigned.

​
Create an Invitation

Generate an invitation token instead of creating a user directly: 
medusa user --email [email protected] --invite
Output: 
info: 
  Invite token: invite_01HQXYZ123ABC456DEF789GHI
  Open the invite in Medusa Admin at: [your-admin-url]/invite?token=invite_01HQXYZ123ABC456DEF789GHI

​
Create User with Custom ID

Specify a custom user ID: 
medusa user --email [email protected] --password SecurePass123 --id user_custom_123

​
Role Assignment

​
With RBAC Enabled

When Role-Based Access Control (RBAC) is enabled:
  • The command automatically assigns the super admin role
  • Super admin role ID: role_super_admin
  • You’ll see: “Assigning super admin role to user.”

​
Without RBAC

When RBAC is not enabled:
  • No role assignment occurs
  • The user is created without specific role limitations

​
Workflow Integration

The command uses Medusa workflows internally:
  • User Creation: create-users-workflow
  • Invitation Creation: create-invite-step
This ensures proper validation, error handling, and integration with Medusa’s authentication system.

​
Authentication Provider

The command uses the emailpass authentication provider to register user credentials. This provider:
  • Stores email/password authentication
  • Hashes passwords securely
  • Links auth identities to user records

​
Common Use Cases

​
First-Time Setup

Create your first admin user after installing Medusa: 
medusa db:setup
medusa user --email [email protected] --password SecurePass123
medusa start

​
Invite New Admin

Generate an invitation link for a new team member: 
medusa user --email [email protected] --invite
Send the invitation URL to your team member: 
https://admin.yourstore.com/invite?token=invite_01HQXYZ123ABC456DEF789GHI

​
Scripted User Creation

Create users non-interactively in deployment scripts: 
#!/bin/bash
medusa user \
  --email [email protected] \
  --password "$ADMIN_PASSWORD" \
  --id user_admin

​
Error Handling

Common errors and their solutions:

​
Email Already Exists

error: A user with email [email protected] already exists
Solution: Use a different email address or update the existing user.

​
Invalid Email Format

error: Invalid email format
Solution: Provide a valid email address.

​
Authentication Provider Error

error: Failed to register authentication credentials
Solution: Check that:
  • The database is accessible
  • The auth module is properly configured
  • No conflicting authentication records exist

​
Security Considerations

​
Password Security

When creating users:
  • Use strong passwords with mixed character types
  • Avoid passing passwords as command-line arguments in production (they appear in shell history)
  • Use environment variables or interactive prompts instead

​
Secure Password Input

# Use interactive mode to avoid shell history
medusa user

# Or use environment variable
medusa user --email [email protected] --password "$ADMIN_PASSWORD"

​
Super Admin Access

Users created with this command receive super admin privileges. Only create users for trusted administrators.

​
Advanced Usage

​
Programmatic User Creation

For more complex user creation scenarios, you can use Medusa workflows directly in your code: 
import { Modules } from "@medusajs/framework/utils"

const workflowService = container.resolve(Modules.WORKFLOW_ENGINE)

const { result: users } = await workflowService.run(
  "create-users-workflow",
  {
    input: {
      users: [
        {
          email: "[email protected]",
          roles: ["role_super_admin"],
        },
      ],
    },
  }
)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us