// Execute mcloud authentication and context commands: login, logout, whoami, use, version, and signup. Use when setting up the CLI, switching accounts, verifying auth state, setting the active org/project/environment context, or checking the CLI version.
| name | mcloud-auth |
| description | Execute mcloud authentication and context commands: login, logout, whoami, use, version, and signup. Use when setting up the CLI, switching accounts, verifying auth state, setting the active org/project/environment context, or checking the CLI version. |
Execute authentication and context commands for the Medusa Cloud CLI.
mcloud login, mcloud signup, and mcloud use (without flags) require a TTY — they fail in CI, Docker, or piped input. Use MCLOUD_TOKEN or pass flags explicitly instead.MCLOUD_TOKEN is set, file-based credentials are ignored and mcloud login is rejected. Unset it to switch accounts.mcloud whoami --json | jq -e '.auth.kind != "none"'Show authenticated user, auth method, and active context (organization, project, environment).
mcloud whoami --json
Options:
--json — Output as JSONUse to verify auth and scope:
mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'
Exit code 0 = authenticated and scoped. Non-zero = stop and prompt the user.
Set the active organization, project, and/or environment so subsequent commands skip those flags.
mcloud use \
--organization <org-id> \
--project <project-id-or-handle> \
--environment <environment-handle>
CRITICAL: mcloud use without flags is interactive and fails in CI/Docker/piped input. Always pass flags explicitly.
Options:
-o/--organization <id> — Set active organization-p/--project <id-or-handle> — Set active project-e/--environment <handle> — Set active environment--clear — Clear all active context--json — Output as JSONClear context:
mcloud use --clear
Print CLI version and platform metadata.
mcloud version --json
Options:
--json — Output as JSONAuthenticate with Medusa Cloud. Opens a browser to complete auth.
TTY required. Cannot be run in CI, Docker, or non-interactive environments. Use
MCLOUD_TOKENinstead for non-interactive auth.
mcloud login
Non-interactive alternative:
export MCLOUD_TOKEN=<access-key>
Options:
-t/--token <token> — Authenticate using an access key without browser (non-interactive)--json — Output as JSONRemove stored credentials.
mcloud logout --json
Options:
--json — Output as JSONCreate a new Medusa Cloud account. Opens a browser.
TTY required. Cannot be run in non-interactive environments.
mcloud signup
| Method | When to use |
|---|---|
mcloud login (browser) | Interactive setup; requires TTY |
mcloud login --token <key> | Non-interactive login with access key |
MCLOUD_TOKEN=<key> env var | CI/CD, Docker, scripted environments |
# Check authentication and active context
mcloud whoami --json
# Verify auth before running commands
mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'
# Set full context (org + project + environment)
mcloud use \
--organization org_123 \
--project my-store \
--environment production
# Set context by resolving names
ORGANIZATION_ID=$(mcloud organizations list --json | jq -r '.[] | select(.name == "My Org") | .id')
PROJECT_HANDLE=$(mcloud projects list --organization "$ORGANIZATION_ID" --json | jq -r '.[] | select(.name == "My Store") | .handle')
ENVIRONMENT_HANDLE=$(mcloud environments list --organization "$ORGANIZATION_ID" --project "$PROJECT_HANDLE" --json | jq -r '.[] | select(.name == "Production") | .handle')
mcloud use \
--organization "$ORGANIZATION_ID" \
--project "$PROJECT_HANDLE" \
--environment "$ENVIRONMENT_HANDLE"
# Clear context
mcloud use --clear
# Check CLI version
mcloud version --json
# Non-interactive login with token
mcloud login --token <access-key>
# Logout
mcloud logout
Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures.
Execute mcloud environments commands to list, get, create, delete, redeploy, or trigger builds for Cloud environments. Use when managing environment lifecycle, redeploying after variable changes, or starting new builds from source.
Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.
Execute mcloud organizations commands to list or get Cloud organizations. Use when discovering organizations, resolving organization IDs by name, or retrieving organization details including members and subscription.
Execute mcloud projects commands to list, get, or delete Cloud projects. Use when discovering projects, resolving project handles by name, or retrieving project details including linked environments.
Execute mcloud variables commands to list and get environment variables for a Cloud environment. Use when inspecting, reading, or exporting environment variables. Never pass --reveal unless the user explicitly requests secret values.