// Manages Medusa Cloud resources through the Cloud CLI (mcloud). Use when deploying, debugging deployments, managing environments, environment variables, or any Medusa Cloud operation. CRITICAL for mcloud commands, deployment failures, build logs, Cloud setup, and CI/CD workflows.
| name | using-medusa-cloud |
| description | Manages Medusa Cloud resources through the Cloud CLI (mcloud). Use when deploying, debugging deployments, managing environments, environment variables, or any Medusa Cloud operation. CRITICAL for mcloud commands, deployment failures, build logs, Cloud setup, and CI/CD workflows. |
Operational guide for AI agents managing Medusa Cloud infrastructure through the mcloud CLI. Covers setup, deployments, debugging, environments, and variables.
--json when parsing CLI output. Plaintext output is for humans and may change without warning.mcloud whoami --json before any state change.get or list before any delete, redeploy, or trigger-build.--yes for destructive operations. delete commands require --yes in non-interactive mode.mcloud environments delete errors on production by design.--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.Load these references based on what you're doing:
setup.md firstdebugging-deployments.md firstenvironments-and-variables.md firstMinimum requirement: Load at least one reference file before executing multi-step workflows.
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.
mcloud use \
--organization org_123 \
--project proj_123 \
--environment production
CRITICAL:
mcloud usewithout flags is interactive and fails in CI/Docker/piped input. Always pass flags.
Route on backend_status (or storefront_status):
| Status | Meaning | Logs to check |
|---|---|---|
build-failed | Build step failed | mcloud deployments build-logs <id> |
deployment-failed | Runtime crashed after build | mcloud logs --deployment <id> |
timed-out | Exceeded time budget | Both: build-logs first, then runtime logs |
| Command | When to use |
|---|---|
mcloud environments redeploy <env> | Fix is environment-side (variable change, infra) — reruns existing build |
mcloud environments trigger-build <env> | Fix is in source code on the tracked branch — starts new build |
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.--organization; org keys are pre-scoped.organizations list requires personal auth. Org access keys return 401 on this command.depl_* = deployment ID; anything else = build ID (resolved to latest deployment). mcloud logs --deployment accepts both; other commands take build IDs only.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
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.
Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures.
Execute mcloud environments commands to list, get, create, delete, redeploy, or trigger builds for Cloud environments. Use when managing environment lifecycle, redeploying after variable changes, or starting new builds from source.
Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.
Execute mcloud organizations commands to list or get Cloud organizations. Use when discovering organizations, resolving organization IDs by name, or retrieving organization details including members and subscription.
Execute mcloud projects commands to list, get, or delete Cloud projects. Use when discovering projects, resolving project handles by name, or retrieving project details including linked environments.