[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-medusa-using-medusa-cloud":3,"mdc--hofmn3-key":43,"related-org-medusa-using-medusa-cloud":989,"related-repo-medusa-using-medusa-cloud":1148},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":27,"repoUrl":28,"updatedAt":29,"license":30,"forks":31,"topics":32,"repo":38,"sourceUrl":41,"mdContent":42},"using-medusa-cloud","manage Medusa Cloud resources","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\u002FCD workflows.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"medusa","Medusa","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fmedusa.jpg","medusajs",[13,15,18,21,24],{"name":9,"slug":8,"type":14},"tag",{"name":16,"slug":17,"type":14},"CLI","cli",{"name":19,"slug":20,"type":14},"E-commerce","e-commerce",{"name":22,"slug":23,"type":14},"Deployment","deployment",{"name":25,"slug":26,"type":14},"Cloud","cloud",197,"https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills","2026-07-17T05:31:35.377629",null,24,[33,34,35,36,37,8],"agentic-commerce","claude","claude-code","commerce","ecommerce",{"repoUrl":28,"stars":27,"forks":31,"topics":39,"description":40},[33,34,35,36,37,8],"Agent skills and commands for Medusa best practices and conventions.","https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills\u002Ftree\u002FHEAD\u002Fplugins\u002Fmedusa-cloud\u002Fskills\u002Fusing-medusa-cloud","---\nname: using-medusa-cloud\ndescription: 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\u002FCD workflows.\n---\n\n# Managing Medusa Cloud Resources\n\nOperational guide for AI agents managing Medusa Cloud infrastructure through the `mcloud` CLI. Covers setup, deployments, debugging, environments, and variables.\n\n## Constraints\n\n- **Always pass `--json`** when parsing CLI output. Plaintext output is for humans and may change without warning.\n- **Confirm context before mutating.** Run `mcloud whoami --json` before any state change.\n- **Read before you write.** Run a `get` or `list` before any `delete`, `redeploy`, or `trigger-build`.\n- **Use `--yes` for destructive operations.** `delete` commands (including `variables delete`) require `--yes` in non-interactive mode.\n- **Variable changes need a deploy to apply.** `variables set`\u002F`delete` don't rebuild or redeploy: `redeploy` for runtime changes, `trigger-build` for build changes.\n- **Production environments cannot be deleted.** `mcloud environments delete` errors on production by design.\n- **Never pass `--reveal` unless the user explicitly asks.** Secret values appear in terminal scrollback and logs.\n- **`--json` and `--follow` are incompatible.** Use bounded time windows (`--from`\u002F`--to`) with `--json` for programmatic log ingestion.\n\n## CRITICAL: Load Reference Files When Needed\n\n**Load these references based on what you're doing:**\n\n- **Setting up the CLI?** → MUST load `setup.md` first\n- **Debugging a failed deployment?** → MUST load `debugging-deployments.md` first\n- **Managing environments or variables?** → MUST load `environments-and-variables.md` first\n\n**Minimum requirement:** Load at least one reference file before executing multi-step workflows.\n\n## Quick Reference\n\n### Authentication Check\n\nAlways verify auth and scope before mutating state:\n\n```bash\nmcloud whoami --json | jq -e '.auth.kind != \"none\" and .organization.id != null'\n```\n\nExit code `0` = authenticated and scoped. Non-zero = stop and ask the user.\n\n### Set Context Once\n\n```bash\nmcloud use \\\n  --organization org_123 \\\n  --project proj_123 \\\n  --environment production\n```\n\n> **CRITICAL:** `mcloud use` without flags is interactive and fails in CI\u002FDocker\u002Fpiped input. Always pass flags.\n\n### Deployment Status Routing\n\nRoute on `backend_status` (or `storefront_status`):\n\n| Status | Meaning | Logs to check |\n|--------|---------|---------------|\n| `build-failed` | Build step failed | `mcloud deployments build-logs \u003Cid>` |\n| `deployment-failed` | Runtime crashed after build | `mcloud logs --deployment \u003Cid>` |\n| `timed-out` | Exceeded time budget | Both: build-logs first, then runtime logs |\n\n### Redeployment Decision\n\n| Command | When to use |\n|---------|-------------|\n| `mcloud environments redeploy \u003Cenv>` | Fix is environment-side (variable change, infra) — reruns existing build |\n| `mcloud environments trigger-build \u003Cenv>` | Fix is in source code on the tracked branch — starts new build |\n\n## Common Pitfalls\n\n- **TTY-only commands.** `mcloud login`, `mcloud use` (without flags), and `delete` without `--yes` require a TTY. They fail in CI, Docker, or piped input.\n- **`MCLOUD_TOKEN` precedence.** When set, file-based credentials are ignored and `mcloud login` is rejected. Unset it to switch accounts.\n- **Personal vs org access keys.** Personal keys require `--organization`; org keys are pre-scoped.\n- **`organizations list` requires personal auth.** Org access keys return 401 on this command.\n- **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.\n- **`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`.\n\n## Reference Files\n\n```\nsetup.md                       - CLI installation, authentication, context setup\ndebugging-deployments.md       - Build\u002Fdeployment failure recipes and log analysis\nenvironments-and-variables.md  - Environment lifecycle and variable management\n```\n",{"data":44,"body":45},{"name":4,"description":6},{"type":46,"children":47},"root",[48,57,72,79,327,333,341,394,404,410,417,422,486,499,505,580,601,607,628,735,741,797,803,967,973,983],{"type":49,"tag":50,"props":51,"children":53},"element","h1",{"id":52},"managing-medusa-cloud-resources",[54],{"type":55,"value":56},"text","Managing Medusa Cloud Resources",{"type":49,"tag":58,"props":59,"children":60},"p",{},[61,63,70],{"type":55,"value":62},"Operational guide for AI agents managing Medusa Cloud infrastructure through the ",{"type":49,"tag":64,"props":65,"children":67},"code",{"className":66},[],[68],{"type":55,"value":69},"mcloud",{"type":55,"value":71}," CLI. Covers setup, deployments, debugging, environments, and variables.",{"type":49,"tag":73,"props":74,"children":76},"h2",{"id":75},"constraints",[77],{"type":55,"value":78},"Constraints",{"type":49,"tag":80,"props":81,"children":82},"ul",{},[83,101,119,169,209,247,264,282],{"type":49,"tag":84,"props":85,"children":86},"li",{},[87,99],{"type":49,"tag":88,"props":89,"children":90},"strong",{},[91,93],{"type":55,"value":92},"Always pass ",{"type":49,"tag":64,"props":94,"children":96},{"className":95},[],[97],{"type":55,"value":98},"--json",{"type":55,"value":100}," when parsing CLI output. Plaintext output is for humans and may change without warning.",{"type":49,"tag":84,"props":102,"children":103},{},[104,109,111,117],{"type":49,"tag":88,"props":105,"children":106},{},[107],{"type":55,"value":108},"Confirm context before mutating.",{"type":55,"value":110}," Run ",{"type":49,"tag":64,"props":112,"children":114},{"className":113},[],[115],{"type":55,"value":116},"mcloud whoami --json",{"type":55,"value":118}," before any state change.",{"type":49,"tag":84,"props":120,"children":121},{},[122,127,129,135,137,143,145,151,153,159,161,167],{"type":49,"tag":88,"props":123,"children":124},{},[125],{"type":55,"value":126},"Read before you write.",{"type":55,"value":128}," Run a ",{"type":49,"tag":64,"props":130,"children":132},{"className":131},[],[133],{"type":55,"value":134},"get",{"type":55,"value":136}," or ",{"type":49,"tag":64,"props":138,"children":140},{"className":139},[],[141],{"type":55,"value":142},"list",{"type":55,"value":144}," before any ",{"type":49,"tag":64,"props":146,"children":148},{"className":147},[],[149],{"type":55,"value":150},"delete",{"type":55,"value":152},", ",{"type":49,"tag":64,"props":154,"children":156},{"className":155},[],[157],{"type":55,"value":158},"redeploy",{"type":55,"value":160},", or ",{"type":49,"tag":64,"props":162,"children":164},{"className":163},[],[165],{"type":55,"value":166},"trigger-build",{"type":55,"value":168},".",{"type":49,"tag":84,"props":170,"children":171},{},[172,185,187,192,194,200,202,207],{"type":49,"tag":88,"props":173,"children":174},{},[175,177,183],{"type":55,"value":176},"Use ",{"type":49,"tag":64,"props":178,"children":180},{"className":179},[],[181],{"type":55,"value":182},"--yes",{"type":55,"value":184}," for destructive operations.",{"type":55,"value":186}," ",{"type":49,"tag":64,"props":188,"children":190},{"className":189},[],[191],{"type":55,"value":150},{"type":55,"value":193}," commands (including ",{"type":49,"tag":64,"props":195,"children":197},{"className":196},[],[198],{"type":55,"value":199},"variables delete",{"type":55,"value":201},") require ",{"type":49,"tag":64,"props":203,"children":205},{"className":204},[],[206],{"type":55,"value":182},{"type":55,"value":208}," in non-interactive mode.",{"type":49,"tag":84,"props":210,"children":211},{},[212,217,218,224,226,231,233,238,240,245],{"type":49,"tag":88,"props":213,"children":214},{},[215],{"type":55,"value":216},"Variable changes need a deploy to apply.",{"type":55,"value":186},{"type":49,"tag":64,"props":219,"children":221},{"className":220},[],[222],{"type":55,"value":223},"variables set",{"type":55,"value":225},"\u002F",{"type":49,"tag":64,"props":227,"children":229},{"className":228},[],[230],{"type":55,"value":150},{"type":55,"value":232}," don't rebuild or redeploy: ",{"type":49,"tag":64,"props":234,"children":236},{"className":235},[],[237],{"type":55,"value":158},{"type":55,"value":239}," for runtime changes, ",{"type":49,"tag":64,"props":241,"children":243},{"className":242},[],[244],{"type":55,"value":166},{"type":55,"value":246}," for build changes.",{"type":49,"tag":84,"props":248,"children":249},{},[250,255,256,262],{"type":49,"tag":88,"props":251,"children":252},{},[253],{"type":55,"value":254},"Production environments cannot be deleted.",{"type":55,"value":186},{"type":49,"tag":64,"props":257,"children":259},{"className":258},[],[260],{"type":55,"value":261},"mcloud environments delete",{"type":55,"value":263}," errors on production by design.",{"type":49,"tag":84,"props":265,"children":266},{},[267,280],{"type":49,"tag":88,"props":268,"children":269},{},[270,272,278],{"type":55,"value":271},"Never pass ",{"type":49,"tag":64,"props":273,"children":275},{"className":274},[],[276],{"type":55,"value":277},"--reveal",{"type":55,"value":279}," unless the user explicitly asks.",{"type":55,"value":281}," Secret values appear in terminal scrollback and logs.",{"type":49,"tag":84,"props":283,"children":284},{},[285,303,305,311,312,318,320,325],{"type":49,"tag":88,"props":286,"children":287},{},[288,293,295,301],{"type":49,"tag":64,"props":289,"children":291},{"className":290},[],[292],{"type":55,"value":98},{"type":55,"value":294}," and ",{"type":49,"tag":64,"props":296,"children":298},{"className":297},[],[299],{"type":55,"value":300},"--follow",{"type":55,"value":302}," are incompatible.",{"type":55,"value":304}," Use bounded time windows (",{"type":49,"tag":64,"props":306,"children":308},{"className":307},[],[309],{"type":55,"value":310},"--from",{"type":55,"value":225},{"type":49,"tag":64,"props":313,"children":315},{"className":314},[],[316],{"type":55,"value":317},"--to",{"type":55,"value":319},") with ",{"type":49,"tag":64,"props":321,"children":323},{"className":322},[],[324],{"type":55,"value":98},{"type":55,"value":326}," for programmatic log ingestion.",{"type":49,"tag":73,"props":328,"children":330},{"id":329},"critical-load-reference-files-when-needed",[331],{"type":55,"value":332},"CRITICAL: Load Reference Files When Needed",{"type":49,"tag":58,"props":334,"children":335},{},[336],{"type":49,"tag":88,"props":337,"children":338},{},[339],{"type":55,"value":340},"Load these references based on what you're doing:",{"type":49,"tag":80,"props":342,"children":343},{},[344,362,378],{"type":49,"tag":84,"props":345,"children":346},{},[347,352,354,360],{"type":49,"tag":88,"props":348,"children":349},{},[350],{"type":55,"value":351},"Setting up the CLI?",{"type":55,"value":353}," → MUST load ",{"type":49,"tag":64,"props":355,"children":357},{"className":356},[],[358],{"type":55,"value":359},"setup.md",{"type":55,"value":361}," first",{"type":49,"tag":84,"props":363,"children":364},{},[365,370,371,377],{"type":49,"tag":88,"props":366,"children":367},{},[368],{"type":55,"value":369},"Debugging a failed deployment?",{"type":55,"value":353},{"type":49,"tag":64,"props":372,"children":374},{"className":373},[],[375],{"type":55,"value":376},"debugging-deployments.md",{"type":55,"value":361},{"type":49,"tag":84,"props":379,"children":380},{},[381,386,387,393],{"type":49,"tag":88,"props":382,"children":383},{},[384],{"type":55,"value":385},"Managing environments or variables?",{"type":55,"value":353},{"type":49,"tag":64,"props":388,"children":390},{"className":389},[],[391],{"type":55,"value":392},"environments-and-variables.md",{"type":55,"value":361},{"type":49,"tag":58,"props":395,"children":396},{},[397,402],{"type":49,"tag":88,"props":398,"children":399},{},[400],{"type":55,"value":401},"Minimum requirement:",{"type":55,"value":403}," Load at least one reference file before executing multi-step workflows.",{"type":49,"tag":73,"props":405,"children":407},{"id":406},"quick-reference",[408],{"type":55,"value":409},"Quick Reference",{"type":49,"tag":411,"props":412,"children":414},"h3",{"id":413},"authentication-check",[415],{"type":55,"value":416},"Authentication Check",{"type":49,"tag":58,"props":418,"children":419},{},[420],{"type":55,"value":421},"Always verify auth and scope before mutating state:",{"type":49,"tag":423,"props":424,"children":429},"pre",{"className":425,"code":426,"language":427,"meta":428,"style":428},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","mcloud whoami --json | jq -e '.auth.kind != \"none\" and .organization.id != null'\n","bash","",[430],{"type":49,"tag":64,"props":431,"children":432},{"__ignoreMap":428},[433],{"type":49,"tag":434,"props":435,"children":438},"span",{"class":436,"line":437},"line",1,[439,444,450,455,461,466,471,476,481],{"type":49,"tag":434,"props":440,"children":442},{"style":441},"--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B",[443],{"type":55,"value":69},{"type":49,"tag":434,"props":445,"children":447},{"style":446},"--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D",[448],{"type":55,"value":449}," whoami",{"type":49,"tag":434,"props":451,"children":452},{"style":446},[453],{"type":55,"value":454}," --json",{"type":49,"tag":434,"props":456,"children":458},{"style":457},"--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF",[459],{"type":55,"value":460}," |",{"type":49,"tag":434,"props":462,"children":463},{"style":441},[464],{"type":55,"value":465}," jq",{"type":49,"tag":434,"props":467,"children":468},{"style":446},[469],{"type":55,"value":470}," -e",{"type":49,"tag":434,"props":472,"children":473},{"style":457},[474],{"type":55,"value":475}," '",{"type":49,"tag":434,"props":477,"children":478},{"style":446},[479],{"type":55,"value":480},".auth.kind != \"none\" and .organization.id != null",{"type":49,"tag":434,"props":482,"children":483},{"style":457},[484],{"type":55,"value":485},"'\n",{"type":49,"tag":58,"props":487,"children":488},{},[489,491,497],{"type":55,"value":490},"Exit code ",{"type":49,"tag":64,"props":492,"children":494},{"className":493},[],[495],{"type":55,"value":496},"0",{"type":55,"value":498}," = authenticated and scoped. Non-zero = stop and ask the user.",{"type":49,"tag":411,"props":500,"children":502},{"id":501},"set-context-once",[503],{"type":55,"value":504},"Set Context Once",{"type":49,"tag":423,"props":506,"children":508},{"className":425,"code":507,"language":427,"meta":428,"style":428},"mcloud use \\\n  --organization org_123 \\\n  --project proj_123 \\\n  --environment production\n",[509],{"type":49,"tag":64,"props":510,"children":511},{"__ignoreMap":428},[512,530,548,566],{"type":49,"tag":434,"props":513,"children":514},{"class":436,"line":437},[515,519,524],{"type":49,"tag":434,"props":516,"children":517},{"style":441},[518],{"type":55,"value":69},{"type":49,"tag":434,"props":520,"children":521},{"style":446},[522],{"type":55,"value":523}," use",{"type":49,"tag":434,"props":525,"children":527},{"style":526},"--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8",[528],{"type":55,"value":529}," \\\n",{"type":49,"tag":434,"props":531,"children":533},{"class":436,"line":532},2,[534,539,544],{"type":49,"tag":434,"props":535,"children":536},{"style":446},[537],{"type":55,"value":538},"  --organization",{"type":49,"tag":434,"props":540,"children":541},{"style":446},[542],{"type":55,"value":543}," org_123",{"type":49,"tag":434,"props":545,"children":546},{"style":526},[547],{"type":55,"value":529},{"type":49,"tag":434,"props":549,"children":551},{"class":436,"line":550},3,[552,557,562],{"type":49,"tag":434,"props":553,"children":554},{"style":446},[555],{"type":55,"value":556},"  --project",{"type":49,"tag":434,"props":558,"children":559},{"style":446},[560],{"type":55,"value":561}," proj_123",{"type":49,"tag":434,"props":563,"children":564},{"style":526},[565],{"type":55,"value":529},{"type":49,"tag":434,"props":567,"children":569},{"class":436,"line":568},4,[570,575],{"type":49,"tag":434,"props":571,"children":572},{"style":446},[573],{"type":55,"value":574},"  --environment",{"type":49,"tag":434,"props":576,"children":577},{"style":446},[578],{"type":55,"value":579}," production\n",{"type":49,"tag":581,"props":582,"children":583},"blockquote",{},[584],{"type":49,"tag":58,"props":585,"children":586},{},[587,592,593,599],{"type":49,"tag":88,"props":588,"children":589},{},[590],{"type":55,"value":591},"CRITICAL:",{"type":55,"value":186},{"type":49,"tag":64,"props":594,"children":596},{"className":595},[],[597],{"type":55,"value":598},"mcloud use",{"type":55,"value":600}," without flags is interactive and fails in CI\u002FDocker\u002Fpiped input. Always pass flags.",{"type":49,"tag":411,"props":602,"children":604},{"id":603},"deployment-status-routing",[605],{"type":55,"value":606},"Deployment Status Routing",{"type":49,"tag":58,"props":608,"children":609},{},[610,612,618,620,626],{"type":55,"value":611},"Route on ",{"type":49,"tag":64,"props":613,"children":615},{"className":614},[],[616],{"type":55,"value":617},"backend_status",{"type":55,"value":619}," (or ",{"type":49,"tag":64,"props":621,"children":623},{"className":622},[],[624],{"type":55,"value":625},"storefront_status",{"type":55,"value":627},"):",{"type":49,"tag":629,"props":630,"children":631},"table",{},[632,656],{"type":49,"tag":633,"props":634,"children":635},"thead",{},[636],{"type":49,"tag":637,"props":638,"children":639},"tr",{},[640,646,651],{"type":49,"tag":641,"props":642,"children":643},"th",{},[644],{"type":55,"value":645},"Status",{"type":49,"tag":641,"props":647,"children":648},{},[649],{"type":55,"value":650},"Meaning",{"type":49,"tag":641,"props":652,"children":653},{},[654],{"type":55,"value":655},"Logs to check",{"type":49,"tag":657,"props":658,"children":659},"tbody",{},[660,687,713],{"type":49,"tag":637,"props":661,"children":662},{},[663,673,678],{"type":49,"tag":664,"props":665,"children":666},"td",{},[667],{"type":49,"tag":64,"props":668,"children":670},{"className":669},[],[671],{"type":55,"value":672},"build-failed",{"type":49,"tag":664,"props":674,"children":675},{},[676],{"type":55,"value":677},"Build step failed",{"type":49,"tag":664,"props":679,"children":680},{},[681],{"type":49,"tag":64,"props":682,"children":684},{"className":683},[],[685],{"type":55,"value":686},"mcloud deployments build-logs \u003Cid>",{"type":49,"tag":637,"props":688,"children":689},{},[690,699,704],{"type":49,"tag":664,"props":691,"children":692},{},[693],{"type":49,"tag":64,"props":694,"children":696},{"className":695},[],[697],{"type":55,"value":698},"deployment-failed",{"type":49,"tag":664,"props":700,"children":701},{},[702],{"type":55,"value":703},"Runtime crashed after build",{"type":49,"tag":664,"props":705,"children":706},{},[707],{"type":49,"tag":64,"props":708,"children":710},{"className":709},[],[711],{"type":55,"value":712},"mcloud logs --deployment \u003Cid>",{"type":49,"tag":637,"props":714,"children":715},{},[716,725,730],{"type":49,"tag":664,"props":717,"children":718},{},[719],{"type":49,"tag":64,"props":720,"children":722},{"className":721},[],[723],{"type":55,"value":724},"timed-out",{"type":49,"tag":664,"props":726,"children":727},{},[728],{"type":55,"value":729},"Exceeded time budget",{"type":49,"tag":664,"props":731,"children":732},{},[733],{"type":55,"value":734},"Both: build-logs first, then runtime logs",{"type":49,"tag":411,"props":736,"children":738},{"id":737},"redeployment-decision",[739],{"type":55,"value":740},"Redeployment Decision",{"type":49,"tag":629,"props":742,"children":743},{},[744,760],{"type":49,"tag":633,"props":745,"children":746},{},[747],{"type":49,"tag":637,"props":748,"children":749},{},[750,755],{"type":49,"tag":641,"props":751,"children":752},{},[753],{"type":55,"value":754},"Command",{"type":49,"tag":641,"props":756,"children":757},{},[758],{"type":55,"value":759},"When to use",{"type":49,"tag":657,"props":761,"children":762},{},[763,780],{"type":49,"tag":637,"props":764,"children":765},{},[766,775],{"type":49,"tag":664,"props":767,"children":768},{},[769],{"type":49,"tag":64,"props":770,"children":772},{"className":771},[],[773],{"type":55,"value":774},"mcloud environments redeploy \u003Cenv>",{"type":49,"tag":664,"props":776,"children":777},{},[778],{"type":55,"value":779},"Fix is environment-side (variable change, infra) — reruns existing build",{"type":49,"tag":637,"props":781,"children":782},{},[783,792],{"type":49,"tag":664,"props":784,"children":785},{},[786],{"type":49,"tag":64,"props":787,"children":789},{"className":788},[],[790],{"type":55,"value":791},"mcloud environments trigger-build \u003Cenv>",{"type":49,"tag":664,"props":793,"children":794},{},[795],{"type":55,"value":796},"Fix is in source code on the tracked branch — starts new build",{"type":49,"tag":73,"props":798,"children":800},{"id":799},"common-pitfalls",[801],{"type":55,"value":802},"Common Pitfalls",{"type":49,"tag":80,"props":804,"children":805},{},[806,843,866,884,900,925],{"type":49,"tag":84,"props":807,"children":808},{},[809,814,815,821,822,827,829,834,836,841],{"type":49,"tag":88,"props":810,"children":811},{},[812],{"type":55,"value":813},"TTY-only commands.",{"type":55,"value":186},{"type":49,"tag":64,"props":816,"children":818},{"className":817},[],[819],{"type":55,"value":820},"mcloud login",{"type":55,"value":152},{"type":49,"tag":64,"props":823,"children":825},{"className":824},[],[826],{"type":55,"value":598},{"type":55,"value":828}," (without flags), and ",{"type":49,"tag":64,"props":830,"children":832},{"className":831},[],[833],{"type":55,"value":150},{"type":55,"value":835}," without ",{"type":49,"tag":64,"props":837,"children":839},{"className":838},[],[840],{"type":55,"value":182},{"type":55,"value":842}," require a TTY. They fail in CI, Docker, or piped input.",{"type":49,"tag":84,"props":844,"children":845},{},[846,857,859,864],{"type":49,"tag":88,"props":847,"children":848},{},[849,855],{"type":49,"tag":64,"props":850,"children":852},{"className":851},[],[853],{"type":55,"value":854},"MCLOUD_TOKEN",{"type":55,"value":856}," precedence.",{"type":55,"value":858}," When set, file-based credentials are ignored and ",{"type":49,"tag":64,"props":860,"children":862},{"className":861},[],[863],{"type":55,"value":820},{"type":55,"value":865}," is rejected. Unset it to switch accounts.",{"type":49,"tag":84,"props":867,"children":868},{},[869,874,876,882],{"type":49,"tag":88,"props":870,"children":871},{},[872],{"type":55,"value":873},"Personal vs org access keys.",{"type":55,"value":875}," Personal keys require ",{"type":49,"tag":64,"props":877,"children":879},{"className":878},[],[880],{"type":55,"value":881},"--organization",{"type":55,"value":883},"; org keys are pre-scoped.",{"type":49,"tag":84,"props":885,"children":886},{},[887,898],{"type":49,"tag":88,"props":888,"children":889},{},[890,896],{"type":49,"tag":64,"props":891,"children":893},{"className":892},[],[894],{"type":55,"value":895},"organizations list",{"type":55,"value":897}," requires personal auth.",{"type":55,"value":899}," Org access keys return 401 on this command.",{"type":49,"tag":84,"props":901,"children":902},{},[903,908,909,915,917,923],{"type":49,"tag":88,"props":904,"children":905},{},[906],{"type":55,"value":907},"Build IDs vs deployment IDs.",{"type":55,"value":186},{"type":49,"tag":64,"props":910,"children":912},{"className":911},[],[913],{"type":55,"value":914},"depl_*",{"type":55,"value":916}," = deployment ID; anything else = build ID (resolved to latest deployment). ",{"type":49,"tag":64,"props":918,"children":920},{"className":919},[],[921],{"type":55,"value":922},"mcloud logs --deployment",{"type":55,"value":924}," accepts both; other commands take build IDs only.",{"type":49,"tag":84,"props":926,"children":927},{},[928,945,947,952,954,959,961,966],{"type":49,"tag":88,"props":929,"children":930},{},[931,937,939,944],{"type":49,"tag":64,"props":932,"children":934},{"className":933},[],[935],{"type":55,"value":936},"mcloud local build",{"type":55,"value":938}," has no ",{"type":49,"tag":64,"props":940,"children":942},{"className":941},[],[943],{"type":55,"value":98},{"type":55,"value":168},{"type":55,"value":946}," It streams plaintext and reports success via its exit code (",{"type":49,"tag":64,"props":948,"children":950},{"className":949},[],[951],{"type":55,"value":496},{"type":55,"value":953}," = success). Requires Docker and must run inside the project's Git repo. Use it to reproduce ",{"type":49,"tag":64,"props":955,"children":957},{"className":956},[],[958],{"type":55,"value":672},{"type":55,"value":960}," failures locally — see ",{"type":49,"tag":64,"props":962,"children":964},{"className":963},[],[965],{"type":55,"value":376},{"type":55,"value":168},{"type":49,"tag":73,"props":968,"children":970},{"id":969},"reference-files",[971],{"type":55,"value":972},"Reference Files",{"type":49,"tag":423,"props":974,"children":978},{"className":975,"code":977,"language":55},[976],"language-text","setup.md                       - CLI installation, authentication, context setup\ndebugging-deployments.md       - Build\u002Fdeployment failure recipes and log analysis\nenvironments-and-variables.md  - Environment lifecycle and variable management\n",[979],{"type":49,"tag":64,"props":980,"children":981},{"__ignoreMap":428},[982],{"type":55,"value":977},{"type":49,"tag":984,"props":985,"children":986},"style",{},[987],{"type":55,"value":988},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":990,"total":1147},[991,1006,1022,1037,1049,1064,1074,1087,1102,1114,1127,1138],{"slug":992,"name":992,"fn":993,"description":994,"org":995,"tags":996,"stars":27,"repoUrl":28,"updatedAt":1005},"building-admin-dashboard-customizations","customize Medusa Admin dashboard UI","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[997,998,1001,1002],{"name":19,"slug":20,"type":14},{"name":999,"slug":1000,"type":14},"Frontend","frontend",{"name":9,"slug":8,"type":14},{"name":1003,"slug":1004,"type":14},"UI Components","ui-components","2026-04-06T18:29:57.203659",{"slug":1007,"name":1007,"fn":1008,"description":1009,"org":1010,"tags":1011,"stars":27,"repoUrl":28,"updatedAt":1021},"building-storefronts","implement Medusa storefront features","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1012,1013,1016,1017,1018],{"name":19,"slug":20,"type":14},{"name":1014,"slug":1015,"type":14},"Engineering","engineering",{"name":999,"slug":1000,"type":14},{"name":9,"slug":8,"type":14},{"name":1019,"slug":1020,"type":14},"React","react","2026-04-06T18:29:55.957429",{"slug":1023,"name":1023,"fn":1024,"description":1025,"org":1026,"tags":1027,"stars":27,"repoUrl":28,"updatedAt":1036},"building-with-medusa","implement Medusa backend features","Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1028,1031,1034,1035],{"name":1029,"slug":1030,"type":14},"Backend","backend",{"name":1032,"slug":1033,"type":14},"Data Modeling","data-modeling",{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},"2026-04-06T18:29:54.652389",{"slug":1038,"name":1038,"fn":1039,"description":1040,"org":1041,"tags":1042,"stars":27,"repoUrl":28,"updatedAt":1048},"creating-agents-in-medusa","build admin-facing AI agents in Medusa","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, buyer-side assistants).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1043,1046,1047],{"name":1044,"slug":1045,"type":14},"Agents","agents",{"name":1029,"slug":1030,"type":14},{"name":9,"slug":8,"type":14},"2026-07-14T05:42:09.367168",{"slug":1050,"name":1050,"fn":1051,"description":1052,"org":1053,"tags":1054,"stars":27,"repoUrl":28,"updatedAt":1063},"db-generate","generate database migrations for Medusa modules","Generate database migrations for a Medusa module",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1055,1056,1059,1060],{"name":1029,"slug":1030,"type":14},{"name":1057,"slug":1058,"type":14},"Database","database",{"name":9,"slug":8,"type":14},{"name":1061,"slug":1062,"type":14},"Migration","migration","2026-04-06T18:29:53.415671",{"slug":1065,"name":1065,"fn":1066,"description":1067,"org":1068,"tags":1069,"stars":27,"repoUrl":28,"updatedAt":1073},"db-migrate","run database migrations in Medusa","Run database migrations in Medusa",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1070,1071,1072],{"name":1057,"slug":1058,"type":14},{"name":9,"slug":8,"type":14},{"name":1061,"slug":1062,"type":14},"2026-04-06T18:29:52.187377",{"slug":1075,"name":1075,"fn":1076,"description":1077,"org":1078,"tags":1079,"stars":27,"repoUrl":28,"updatedAt":1086},"learning-medusa","guide Medusa development learning","Load automatically when user asks to learn Medusa development (e.g., \"teach me how to build with medusa\", \"guide me through medusa\", \"I want to learn medusa\"). Interactive guided tutorial where Claude acts as a coding bootcamp instructor, teaching step-by-step with checkpoints and verification.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1080,1081,1082,1083],{"name":1029,"slug":1030,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":1084,"slug":1085,"type":14},"Templates","templates","2026-04-06T18:29:58.461689",{"slug":1088,"name":1088,"fn":1089,"description":1090,"org":1091,"tags":1092,"stars":27,"repoUrl":28,"updatedAt":1101},"mcloud-deployments","manage Medusa Cloud deployments","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1093,1094,1097,1098],{"name":22,"slug":23,"type":14},{"name":1095,"slug":1096,"type":14},"Logs","logs",{"name":9,"slug":8,"type":14},{"name":1099,"slug":1100,"type":14},"Observability","observability","2026-05-09T05:40:51.727369",{"slug":1103,"name":1103,"fn":1104,"description":1105,"org":1106,"tags":1107,"stars":27,"repoUrl":28,"updatedAt":1113},"mcloud-environments","manage Medusa Cloud environments","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1108,1109,1110],{"name":22,"slug":23,"type":14},{"name":9,"slug":8,"type":14},{"name":1111,"slug":1112,"type":14},"Operations","operations","2026-07-17T05:31:36.384292",{"slug":1115,"name":1115,"fn":1116,"description":1117,"org":1118,"tags":1119,"stars":27,"repoUrl":28,"updatedAt":1126},"mcloud-local","reproduce Cloud builds locally","Execute mcloud local build to reproduce a Cloud build on the local machine. Use when debugging a build-failed deployment without pushing to the tracked branch, iterating on a build fix, or testing build-variable changes locally. Requires Docker and must run inside the project's Git repo.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1120,1123,1124,1125],{"name":1121,"slug":1122,"type":14},"Debugging","debugging",{"name":22,"slug":23,"type":14},{"name":1014,"slug":1015,"type":14},{"name":9,"slug":8,"type":14},"2026-07-17T06:05:07.199529",{"slug":1128,"name":1128,"fn":1129,"description":1130,"org":1131,"tags":1132,"stars":27,"repoUrl":28,"updatedAt":1137},"mcloud-logs","fetch and stream runtime cloud logs","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1133,1134,1135,1136],{"name":25,"slug":26,"type":14},{"name":1095,"slug":1096,"type":14},{"name":9,"slug":8,"type":14},{"name":1099,"slug":1100,"type":14},"2026-05-09T05:40:46.707854",{"slug":1139,"name":1139,"fn":1140,"description":1141,"org":1142,"tags":1143,"stars":27,"repoUrl":28,"updatedAt":1146},"mcloud-organizations","manage Medusa Cloud organizations","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1144,1145],{"name":9,"slug":8,"type":14},{"name":1111,"slug":1112,"type":14},"2026-05-09T05:40:54.327722",17,{"items":1149,"total":1147},[1150,1157,1165,1172,1178,1185,1191],{"slug":992,"name":992,"fn":993,"description":994,"org":1151,"tags":1152,"stars":27,"repoUrl":28,"updatedAt":1005},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1153,1154,1155,1156],{"name":19,"slug":20,"type":14},{"name":999,"slug":1000,"type":14},{"name":9,"slug":8,"type":14},{"name":1003,"slug":1004,"type":14},{"slug":1007,"name":1007,"fn":1008,"description":1009,"org":1158,"tags":1159,"stars":27,"repoUrl":28,"updatedAt":1021},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1160,1161,1162,1163,1164],{"name":19,"slug":20,"type":14},{"name":1014,"slug":1015,"type":14},{"name":999,"slug":1000,"type":14},{"name":9,"slug":8,"type":14},{"name":1019,"slug":1020,"type":14},{"slug":1023,"name":1023,"fn":1024,"description":1025,"org":1166,"tags":1167,"stars":27,"repoUrl":28,"updatedAt":1036},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1168,1169,1170,1171],{"name":1029,"slug":1030,"type":14},{"name":1032,"slug":1033,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"slug":1038,"name":1038,"fn":1039,"description":1040,"org":1173,"tags":1174,"stars":27,"repoUrl":28,"updatedAt":1048},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1175,1176,1177],{"name":1044,"slug":1045,"type":14},{"name":1029,"slug":1030,"type":14},{"name":9,"slug":8,"type":14},{"slug":1050,"name":1050,"fn":1051,"description":1052,"org":1179,"tags":1180,"stars":27,"repoUrl":28,"updatedAt":1063},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1181,1182,1183,1184],{"name":1029,"slug":1030,"type":14},{"name":1057,"slug":1058,"type":14},{"name":9,"slug":8,"type":14},{"name":1061,"slug":1062,"type":14},{"slug":1065,"name":1065,"fn":1066,"description":1067,"org":1186,"tags":1187,"stars":27,"repoUrl":28,"updatedAt":1073},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1188,1189,1190],{"name":1057,"slug":1058,"type":14},{"name":9,"slug":8,"type":14},{"name":1061,"slug":1062,"type":14},{"slug":1075,"name":1075,"fn":1076,"description":1077,"org":1192,"tags":1193,"stars":27,"repoUrl":28,"updatedAt":1086},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1194,1195,1196,1197],{"name":1029,"slug":1030,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":1084,"slug":1085,"type":14}]