medusa user

Learn how to create admin users with the Medusa CLI.

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 [e-mail]

• Type: string
• Required: Yes (prompted if not provided)

-p, --password <password>

The password for the user.

medusa user --email [e-mail] --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 [e-mail] --id user_123

• Type: string
• Default: Auto-generated

--invite

Create an invitation instead of a user directly.

medusa user --email [e-mail] --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: [e-mail]
? Password: ••••••••••••

Examples

Create a User

Create a new admin user with email and password:

medusa user --email [e-mail] --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: [e-mail]
? 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 [e-mail] --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 [e-mail] --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 [e-mail] --password SecurePass123
medusa start

Invite New Admin

Generate an invitation link for a new team member:

medusa user --email [e-mail] --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 [e-mail] \
  --password "$ADMIN_PASSWORD" \
  --id user_admin

Error Handling

Common errors and their solutions:

Email Already Exists

error: A user with email [e-mail] 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 [e-mail] --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: "[e-mail]",
          roles: ["role_super_admin"],
        },
      ],
    },
  }
)

See Also

• API Authentication - Learn about authentication in Medusa
• Admin Dashboard - Admin dashboard overview
• Auth Providers - Configure authentication providers