---
name: Using Medusa Cloud
slug: using-medusa-cloud
category: DevOps
description: Using Medusa Cloud manages Medusa Cloud resources through the mcloud CLI. Use it for deployments, debugging failures, environments, environment variables, and CI/CD workflows.
github: "https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/medusa-cloud/skills/using-medusa-cloud"
language: JavaScript
stars: 212
forks: 26
install: "npx degit https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/medusa-cloud/skills/using-medusa-cloud ~/.claude/skills/using-medusa-cloud"
installs_to: ~/.claude/skills/using-medusa-cloud
source_path: plugins/medusa-cloud/skills/using-medusa-cloud/SKILL.md
collection_size: 18
category_size: 920
collection_url: "https://dirskills.com/collections/medusajs/medusa-agent-skills"
added: 2026-09-04T05:26:10.344Z
last_synced: 2026-09-04T05:26:10.344Z
canonical_url: "https://dirskills.com/skills/using-medusa-cloud"
---

# Using Medusa Cloud

Using Medusa Cloud manages Medusa Cloud resources through the mcloud CLI. Use it for deployments, debugging failures, environments, environment variables, and CI/CD workflows.

**Install:**

```bash
npx degit https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/medusa-cloud/skills/using-medusa-cloud ~/.claude/skills/using-medusa-cloud
```

## README

# 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 (including `variables delete`) require `--yes` in non-interactive mode.
- **Variable changes need a deploy to apply.** `variables set`/`delete` don't rebuild or redeploy: `redeploy` for runtime changes, `trigger-build` for build changes.
- **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:

```bash
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

```bash
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`):

| 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 |

### Redeployment Decision

| 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 |

## 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.
- **`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`.

## 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
```