/mcloud-auth

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

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

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