Using Medusa Cloud

Managing Medusa Cloud Resources

Operational guide for AI agents managing Medusa Cloud infrastructure through the mcloud CLI. Covers setup, deployments, debugging, environments, and variables.

Constraints

• Always pass `--json` when parsing CLI output. Plaintext output is for humans and may change without warning.
• Confirm context before mutating. Run mcloud whoami --json before any state change.
• Read before you write. Run a get or list before any delete, redeploy, or trigger-build.
• Use `--yes` for destructive operations. delete commands require --yes in non-interactive mode.
• Production environments cannot be deleted. mcloud environments delete errors on production by design.
• Never pass `--reveal` unless the user explicitly asks. Secret values appear in terminal scrollback and logs.
• `--json` and `--follow` are incompatible. Use bounded time windows (--from/--to) with --json for programmatic log ingestion.

CRITICAL: Load Reference Files When Needed

Load these references based on what you're doing:

• Setting up the CLI? → MUST load setup.md first
• Debugging a failed deployment? → MUST load debugging-deployments.md first
• Managing environments or variables? → MUST load environments-and-variables.md first

Minimum requirement: Load at least one reference file before executing multi-step workflows.

Quick Reference

Authentication Check

Always verify auth and scope before mutating state:

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

Exit code 0 = authenticated and scoped. Non-zero = stop and ask the user.

Set Context Once

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

CRITICAL: mcloud use without flags is interactive and fails in CI/Docker/piped input. Always pass flags.

Deployment Status Routing

Route on backend_status (or storefront_status):

Redeployment Decision

Common Pitfalls

• TTY-only commands. mcloud login, mcloud use (without flags), and delete without --yes require a TTY. They fail in CI, Docker, or piped input.
• `MCLOUD_TOKEN` precedence. When set, file-based credentials are ignored and mcloud login is rejected. Unset it to switch accounts.
• Personal vs org access keys. Personal keys require --organization; org keys are pre-scoped.
• `organizations list` requires personal auth. Org access keys return 401 on this command.
• Build IDs vs deployment IDs. depl_* = deployment ID; anything else = build ID (resolved to latest deployment). mcloud logs --deployment accepts both; other commands take build IDs only.

Reference Files

setup.md                       - CLI installation, authentication, context setup
debugging-deployments.md       - Build/deployment failure recipes and log analysis
environments-and-variables.md  - Environment lifecycle and variable management

Debugging Deployments

Inspecting Deployments

Status fields per deployment: backend_status and storefront_status.

Values: created, building, built, deploying, deployed, build-failed, deployment-failed, timed-out (backend only), canceled, idle.

# Most recent failed deployment
mcloud deployments list --json \
  | jq -r '[.[] | select(.backend_status == "build-failed" or .backend_status == "deployment-failed")][0].id'

# Deployments for a specific commit
mcloud deployments list --commit a1b2c3d --json | jq '.'

# Only preview deployments
mcloud deployments list --environment-type preview --json | jq '.'

# Single deployment details
mcloud deployments get bld_01ABC123 --json

Build Failure Recipe

Use when backend_status == "build-failed":

# Find the most recent build-failed deployment
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'
)

# Inspect deployment metadata
mcloud deployments get "$DEPLOYMENT_ID" --json

# Read the build output
mcloud deployments build-logs "$DEPLOYMENT_ID"

# For storefront build failures
mcloud deployments build-logs "$DEPLOYMENT_ID" --type storefront

build-logs returns a build_status field. When failed, check metadata.failed_docker_layer via mcloud deployments get --json to identify the failing layer.

Deployment Failure Recipe

Use when backend_status == "deployment-failed" (build succeeded, runtime crashed):

# Find the most recent deployment-failed
DEPLOYMENT_ID=$(
  mcloud deployments list --json \
    | jq -r '[.[] | select(.backend_status == "deployment-failed")][0].id'
)

# Runtime logs for that deployment
mcloud logs --deployment "$DEPLOYMENT_ID" --limit 1000

# Error-level lines only
mcloud logs --deployment "$DEPLOYMENT_ID" --search error --limit 1000

# Filter by HTTP status
mcloud logs --deployment "$DEPLOYMENT_ID" --metadata status=500 --limit 1000

# Structured analysis
mcloud logs --deployment "$DEPLOYMENT_ID" --json | jq '.[] | {timestamp, source, message}'

Note: --follow cannot be combined with --json. Use bounded time windows with --from/--to and --json for scripts.

Rerunning a Deployment

Two options — not interchangeable:

Redeploy (environment-side fix): Re-runs the active deployment's existing build. Use when the fix is a variable change or infra issue.

mcloud environments redeploy env_123

Requires the environment to have an active deployment. If it doesn't, use trigger-build first.

Trigger build (source code fix): Starts a new build from the tracked branch. Use when the fix is in committed code.

mcloud environments trigger-build env_123

Verify the new build:

mcloud deployments list --environment env_123 --limit 5 --json \
  | jq '.[] | {id, backend_status, commit_hash, updated_at}'

Environments and Variables

Managing Environments

Create a Preview Environment

mcloud environments create \
  --name "Staging" \
  --branch develop

Inspect an Environment

mcloud environments get staging --json | jq '{id, name, type, status, external_id}'

Delete an Environment

mcloud environments delete env_123 --yes

CRITICAL: Production environments are protected — delete returns a non-zero exit code. Always check the type field via environments get --json before attempting a delete in automation.

Managing Environment Variables

Variables are scoped to a single environment.

List Variables

mcloud variables list --json

Get a Variable

# By key (requires active project and environment)
mcloud variables get DATABASE_URL --json

# By ID (works without project/environment context)
mcloud variables get var_01XYZ --json

Reveal Secret Values

CRITICAL: Only pass --reveal when the user explicitly asks. Plaintext values appear in terminal scrollback, log aggregators, and process listings.

mcloud variables get STRIPE_SECRET_KEY --reveal --json | jq -r '.value'

Export to .env

Replicate a Cloud environment's variables locally:

mcloud variables list --reveal --json \
  | jq -r '.[] | "\(.key)=\(.value)"' \
  > .env

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