version: "1.0.1" 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." allowed-tools: Bash(mcloud whoami), Bash(mcloud use), Bash(mcloud version), Bash(mcloud logout), Bash(jq*)

Cloud CLI: Auth and Context Commands

Execute authentication and context commands for the Medusa Cloud CLI.

Constraints

• 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.
• When MCLOUD_TOKEN is set, file-based credentials are ignored and mcloud login is rejected. Unset it to switch accounts.
• Always verify auth before any state-changing command: mcloud whoami --json | jq -e '.auth.kind != "none"'

Commands

whoami

Show authenticated user, auth method, and active context (organization, project, environment).

mcloud whoami --json

Options:

• --json — Output as JSON

Use 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.

use

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 JSON

Clear context:

mcloud use --clear

version

Print CLI version and platform metadata.

mcloud version --json

Options:

• --json — Output as JSON

login

Authenticate with Medusa Cloud. Opens a browser to complete auth.

TTY required. Cannot be run in CI, Docker, or non-interactive environments. Use MCLOUD_TOKEN instead 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 JSON

logout

Remove stored credentials.

mcloud logout --json

Options:

• --json — Output as JSON

signup

Create a new Medusa Cloud account. Opens a browser.

TTY required. Cannot be run in non-interactive environments.

mcloud signup

Auth Methods

Examples

# 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