Terminal
Terminal/Skill
Manages Medusa Cloud deployments, environments and environment variables through the mcloud CLI, including deployment failures and CI/CD setup.
By Medusa
Works with
npx skills add medusajs/medusa-agent-skills --skill using-medusa-cloudOperational 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 (including variables delete) require --yes in non-interactive mode.variables set/delete don't rebuild or redeploy: redeploy for runtime changes, trigger-build for build changes.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.mcloud local build has no --json. It streams plaintext and reports success via its exit code (0 = success). Requires Docker and must run inside the project's Git repo. Use it to reproduce build-failed failures locally — see debugging-deployments.md.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