Index of every page on this site: llms.txt
All skills
medusajs avatar

/using-medusa-cloud

@c5a56b4 official
by Medusamedusajs/medusa-agent-skills237 stars
29
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/medusajs/medusa-agent-skills/using-medusa-cloud

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈75 tokens for metadata: the name and description. ≈1k when used: this file. ≈2.7k more on demand in 3 files.

Description uses 3.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈300 characters, or 3.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill is a utility for managing Medusa Cloud resources using the official mcloud CLI. It incorporates security best practices, such as requiring explicit user confirmation for revealing secrets and protecting production environments from accidental deletion.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at c5a56b4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 4 months ago

README badge

README badge for medusajs/medusa-agent-skills/using-medusa-cloud