/using-medusa-cloud

CLI Setup and Authentication

One-time setup for the Medusa Cloud CLI. Skip steps whose checks already pass.

1. Check if CLI is Installed

mcloud --version

If this exits 0 and prints a version, skip to Confirm Authentication.

2. Verify Node.js Version

The CLI requires Node.js v22+:

node --version

If below v22, ask the user to upgrade (via nvm or the official installer). Do not upgrade without authorization.

3. Install the CLI

npm install -g @medusajs/mcloud

Verify:

mcloud --version

If not found, ask the user to check their global npm bin directory is on PATH.

4. Confirm Authentication

Ask the user if they have a Medusa Cloud account.

Has account:

mcloud login

Opens a browser to complete auth.

No account:

mcloud signup
mcloud login

Non-interactive environments (CI, Docker, headless):

export MCLOUD_TOKEN=<access-key>

When MCLOUD_TOKEN is set, the CLI uses it on every command and mcloud login is rejected.

5. Verify Setup

mcloud whoami --json

Check auth and scope:

mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'

Setting the Active Context

Persist org, project, and environment so subsequent commands skip --organization, --project, --environment flags:

mcloud use \
  --organization org_123 \
  --project proj_123 \
  --environment production

Resolving Names to IDs

If you only have names:

# Resolve organization ID by name
ORGANIZATION_ID=$(
  mcloud organizations list --json \
    | jq -r '.[] | select(.name == "My Organization") | .id'
)

# Resolve project handle by name
PROJECT_HANDLE=$(
  mcloud projects list --organization "$ORGANIZATION_ID" --json \
    | jq -r '.[] | select(.name == "My Store") | .handle'
)

# Resolve environment handle by name
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"

Clearing Context

mcloud use --clear