Setting the file. One moment.
Subchapter 11.3
reference/setup.mdMarkdown2 KBView on GitHub
One-time setup for the Medusa Cloud CLI. Skip steps whose checks already pass.
mcloud --versionIf this exits 0 and prints a version, skip to Confirm Authentication.
The CLI requires Node.js v22+:
node --versionIf below v22, ask the user to upgrade (via nvm or the official installer). Do not upgrade without authorization.
npm install -g @medusajs/mcloudVerify:
mcloud --versionIf not found, ask the user to check their global npm bin directory is on PATH.
Ask the user if they have a Medusa Cloud account.
Has account:
mcloud loginOpens a browser to complete auth.
No account:
mcloud signup
mcloud loginNon-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.
mcloud whoami --jsonCheck auth and scope:
mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'Persist org, project, and environment so subsequent commands skip --organization, --project, --environment flags:
mcloud use \
--organization org_123 \
--project proj_123 \
--environment productionIf 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"mcloud use --clear