login Command - Medusa Cloud CLI Reference

Authenticate with Cloud and store your credentials on disk. This is essential before running other Cloud CLI commands.

Terminal
❯mcloud login

Running the command without options opens a browser window where you complete the login flow. After a successful login, your credentials are stored on your machine and reused automatically by subsequent CLI commands.

When the MCLOUD_TOKEN environment variable is set, mcloud login cannot be called. The CLI rejects it because the environment variable takes precedence. Use mcloud login only when MCLOUD_TOKEN is not set.

Options#

Authenticate Locally#

After installing the CLI, run mcloud login without setting MCLOUD_TOKEN. A browser will open to login with your Cloud account. After you complete the login flow, your credentials are stored locally and used automatically by subsequent commands.

Terminal
❯mcloud login

After login, the CLI infers and saves a default context (organization, project, and the production environment if available) so subsequent commands can run without --organization, --project, or --environment flags. You can change the active context at any time with mcloud use.

To log out, run mcloud logout to clear your credentials from disk.

Non-Interactive Authentication#

If you don't have access to a browser, you prefer non-interactive authentication, or you're using the CLI in CI/CD pipelines and other automated environments, set the MCLOUD_TOKEN environment variable to your access key. The CLI reads it directly on every command invocation, and you do not need to call mcloud login at all.

Cloud supports two types of access keys for non-interactive authentication. The type you use determines whether you need to pass --organization on commands that scope to an organization.

• Personal access key: Generated from your account settings in the Cloud dashboard. Grants access to every organization you belong to, so you must specify which organization to target by passing --organization on every command that requires it, or by setting it once with mcloud use --organization <id>.
• Organization access key: Generated from an organization's settings in the Cloud dashboard. Scoped to that specific organization, so --organization is never required.

Terminal
❯# Set once in your CI platform as a secret❯export MCLOUD_TOKEN=sk_123ABC❯# Then run commands as normal without passing --token or --organization (if using an organization access key)❯mcloud environments list --project my-store❯mcloud logs --project my-store --environment production --follow

With a Personal Access Key#

Personal access keys require an organization ID. Pass --organization on each command, or set it once with mcloud use --organization <id> so all subsequent commands use it automatically:

Terminal
❯# Personal access key set as a secret in your CI platform❯export MCLOUD_TOKEN=sk_123ABC❯
❯# Persist the active organization in the context configuration❯mcloud use --organization org_01ABC123❯
❯mcloud environments list --project proj_123❯mcloud logs --project proj_123 --environment production --follow❯
❯# Switch to a different organization later❯mcloud use --organization org_01DEF456❯mcloud environments list --project proj_123

With an Organization Access Key#

Organization access keys are already scoped to one organization, so you don't need to set the active organization or pass --organization on commands:

Terminal
❯# Set organization access key as a secret in your CI platform❯export MCLOUD_TOKEN=sk_123ABC❯
❯mcloud environments list --project proj_123❯mcloud logs --project proj_123 --environment production --follow

Logging Out of Non-Interactive Authentication#

To log out when using MCLOUD_TOKEN, unset the environment variable:

Terminal
❯unset MCLOUD_TOKEN

Subsequent commands will fail until you either set MCLOUD_TOKEN again or run mcloud login to authenticate with a browser and store credentials on disk.