using-medusa-cloud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Medusa Cloud Resources

管理Medusa Cloud资源

Operational guide for AI agents managing Medusa Cloud infrastructure through the

mcloud

CLI. Covers setup, deployments, debugging, environments, and variables.

本指南为AI Agent提供通过

mcloud

CLI管理Medusa Cloud基础设施的操作说明，涵盖配置、部署、调试、环境及变量管理等内容。

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 require
```
--yes
```
in non-interactive mode.
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.

解析CLI输出时务必添加
--json
参数：纯文本输出面向人类用户，可能会无预警变更。
执行变更操作前确认上下文：在任何状态变更前运行
```
mcloud whoami --json
```
。
先读取再写入：执行
```
delete
```
、
```
redeploy
```
或
```
trigger-build
```
命令前，先运行
```
get
```
或
```
list
```
命令。
破坏性操作需添加
--yes
参数：非交互模式下，
```
delete
```
命令必须携带
```
--yes
```
才能执行。
生产环境无法删除：
```
mcloud environments delete
```
命令在生产环境下会触发错误，这是设计使然。
除非用户明确要求，否则绝不使用
--reveal
参数：敏感值会出现在终端回滚记录和日志中。
--json
与
--follow
参数互斥：如需以编程方式采集日志，可结合
```
--json
```
和时间范围参数（
```
--from
```
/
```
--to
```
）。

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.

根据当前操作加载对应参考文件：

配置CLI？ → 必须先加载
```
setup.md
```
排查部署故障？ → 必须先加载
```
debugging-deployments.md
```
管理环境或变量？ → 必须先加载
```
environments-and-variables.md
```

最低要求：执行多步骤工作流前，至少加载一个参考文件。

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

= authenticated and scoped. Non-zero = stop and ask the user.

执行状态变更操作前，务必验证身份验证状态和权限范围：

bash

mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'

退出码

= 已通过身份验证且权限范围正确。非零退出码 = 停止操作并询问用户。

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.

bash

mcloud use \
  --organization org_123 \
  --project proj_123 \
  --environment production

重要提示： 不带参数的
mcloud use
为交互式命令，在CI、Docker或管道输入环境下会执行失败。务必携带参数运行。

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

根据

backend_status

（或

storefront_status

）进行路由处理：

状态	含义	需检查的日志
`build-failed`	构建步骤失败	`mcloud deployments build-logs <id>`
`deployment-failed`	构建完成后运行时崩溃	`mcloud logs --deployment <id>`
`timed-out`	超出时间预算	需检查两者：先查看构建日志，再查看运行时日志

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

命令	使用场景
`mcloud environments redeploy <env>`	修复操作针对环境侧（如变量变更、基础设施调整）——重新运行现有构建
`mcloud environments trigger-build <env>`	修复操作针对跟踪分支中的源代码——启动新的构建

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.

仅支持TTY的命令：
```
mcloud login
```
、不带参数的
```
mcloud use
```
以及未携带
```
--yes
```
的
```
delete
```
命令需要TTY环境。在CI、Docker或管道输入环境下会执行失败。
MCLOUD_TOKEN
的优先级：当该环境变量被设置时，基于文件的凭据会被忽略，且
```
mcloud login
```
命令会被拒绝。如需切换账户，请取消设置该变量。
个人访问密钥 vs 组织访问密钥：个人访问密钥需要携带
```
--organization
```
参数；组织访问密钥已预先设置权限范围。
organizations list
命令需要个人身份验证：使用组织访问密钥执行该命令会返回401错误。
构建ID vs 部署ID：
```
depl_*
```
= 部署ID；其他格式 = 构建ID（会解析为最新部署）。
```
mcloud logs --deployment
```
命令两者都接受；其他命令仅支持构建ID。

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

setup.md                       - CLI安装、身份验证、上下文配置
debugging-deployments.md       - 构建/部署故障排查方案及日志分析
environments-and-variables.md  - 环境生命周期及变量管理