medusajs/medusa-agent-skills

using-medusa-cloud

Manages Medusa Cloud resources through the Cloud CLI (mcloud).

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/medusajs/medusa-agent-skills --skill using-medusa-cloud

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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

StatusMeaningLogs to check
build-failedBuild step failedmcloud deployments build-logs <id>
deployment-failedRuntime crashed after buildmcloud logs --deployment <id>
timed-outExceeded time budgetBoth: build-logs first, then runtime logs

Redeployment Decision

CommandWhen 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

タスクに関連する項目

同じリポジトリから

関連する Skills

すべての Skills
medusajs
公式

building-admin-dashboard-customizations

Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.

1時間の導入数
2
GitHub Stars
237
更新日
11月13日
medusajs
公式

storefront-best-practices

ALWAYS use this skill when working on ecommerce storefronts, online stores, shopping sites. Use for ANY storefront component including checkout pages, cart, payment flows, product pages, product listings, navigation, homepage, or ANY page/component in a storefront. CRITICAL for adding checkout, implementing cart, integrating Medusa backend, making a store agent-friendly for AI shopping agents, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React,

1時間の導入数
2
GitHub Stars
234
更新日
10月21日
medusajs
公式

building-storefronts

Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.

1時間の導入数
1
GitHub Stars
234
更新日
10月21日
medusajs
公式

creating-internal-agents

Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, b

1時間の導入数
1
GitHub Stars
234
更新日
10月21日