> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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.

```bash theme={null}
medusa user --email admin@example.com
```

* Type: `string`
* Required: Yes (prompted if not provided)

### `-p`, `--password <password>`

The password for the user.

```bash theme={null}
medusa user --email admin@example.com --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.

```bash theme={null}
medusa user --email admin@example.com --id user_123
```

* Type: `string`
* Default: Auto-generated

### `--invite`

Create an invitation instead of a user directly.

```bash theme={null}
medusa user --email admin@example.com --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:

```bash theme={null}
medusa user
```

You'll see prompts like:

```bash theme={null}
? Email: admin@example.com
? Password: ••••••••••••
```

## Examples

### Create a User

Create a new admin user with email and password:

```bash theme={null}
medusa user --email admin@example.com --password SecurePass123
```

Output:

```bash theme={null}
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:

```bash theme={null}
medusa user
```

Interactive prompts:

```bash theme={null}
? Email: admin@example.com
? 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:

```bash theme={null}
medusa user --email newadmin@example.com --invite
```

Output:

```bash theme={null}
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:

```bash theme={null}
medusa user --email admin@example.com --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:

```bash theme={null}
medusa db:setup
medusa user --email admin@example.com --password SecurePass123
medusa start
```

### Invite New Admin

Generate an invitation link for a new team member:

```bash theme={null}
medusa user --email teammate@example.com --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:

```bash theme={null}
#!/bin/bash
medusa user \
  --email admin@example.com \
  --password "$ADMIN_PASSWORD" \
  --id user_admin
```

## Error Handling

Common errors and their solutions:

### Email Already Exists

```bash theme={null}
error: A user with email admin@example.com already exists
```

**Solution**: Use a different email address or update the existing user.

### Invalid Email Format

```bash theme={null}
error: Invalid email format
```

**Solution**: Provide a valid email address.

### Authentication Provider Error

```bash theme={null}
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

```bash theme={null}
# Use interactive mode to avoid shell history
medusa user

# Or use environment variable
medusa user --email admin@example.com --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:

```typescript theme={null}
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: "admin@example.com",
          roles: ["role_super_admin"],
        },
      ],
    },
  }
)
```

## See Also

* [API Authentication](/api/authentication) - Learn about authentication in Medusa
* [Admin Dashboard](/admin/overview) - Admin dashboard overview
* [Auth Providers](/providers/auth) - Configure authentication providers