mcloud-variables

Cloud CLI：变量命令

执行 mcloud variables 命令，以检查和管理 Cloud 环境的环境变量。

限制

• 除非用户明确要求，否则绝不要传入 --reveal。 密钥值会出现在终端滚屏内容、日志聚合器和进程列表中。
• 变量更改需要部署才能生效。 set/delete 不会重新构建或重新部署。对于运行时变量，请运行 mcloud environments redeploy <env>；对于构建变量，请运行 mcloud environments trigger-build <env>（重新部署会复用现有镜像，因此不会获取构建变量的更改）。
• 系统变量无法删除，且在非交互模式下，delete 需要 --yes。
• 按键查找或创建变量需要 --project 和 --environment（或在当前上下文中设置等效信息）。按 ID（var_...）引用则无需项目/环境上下文。
• set 和 delete 需要 mcloud CLI v0.1.10+。

命令

variables list

列出 Cloud 环境的所有环境变量。

mcloud variables list \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle> \
  --json

选项：

• -o/--organization <id> — 组织 ID（回退到当前上下文）
• -p/--project <id-or-handle> — 项目 ID 或句柄（回退到当前上下文）
• -e/--environment <handle> — 环境句柄（回退到当前上下文）
• -t/--type <backend|storefront> — 要列出的变量集（默认：backend）
• --scope <build|runtime> — 按作用范围筛选；可重复指定（默认：两个作用范围）
• --include-system — 包含 Medusa 自动注入的系统变量（默认：false）
• --reveal — 以明文而非掩码形式打印密钥值（仅在用户明确要求时使用）
• --dotenv — 输出 .env 格式的 KEY=VALUE 行，而非表格
• --json — 以 JSON 格式输出

variables get

按 ID（var_...）或键获取单个变量。

# By key (requires project + environment context)
mcloud variables get ADMIN_CORS \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle> \
  --json

# By ID (works without project/environment context)
mcloud variables get var_01XYZ --json

参数：

• variable — 变量 ID（var_...）或键（必填）

选项：

• -o/--organization <id>、-p/--project <id-or-handle>、-e/--environment <handle>
• -t/--type <backend|storefront> — 要读取的变量集（默认：backend）
• --reveal — 以明文打印密钥值（仅在用户明确要求时使用）
• --json — 以 JSON 格式输出

variables set

创建或更新一个或多个变量。引用现有键或 var_... ID 时，CLI 会更新变量；否则会创建变量。

# Single variable
mcloud variables set API_KEY pk_123 \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle>

# Multiple at once
mcloud variables set -v API_KEY=pk_123 -v CLIENT_ID=my_app

# From a .env file
mcloud variables set --env-file .env

参数：

• variable — 要设置的变量 ID（var_...）或键（使用 --var/--env-file 时省略）
• value — 要设置的值（传入 variable 参数时必填）

选项：

• -o/--organization <id>、-p/--project <id-or-handle>、-e/--environment <handle>
• -t/--type <backend|storefront> — 要写入的变量集（默认：backend）
• -v/--var <KEY=VALUE|ID=VALUE> — 要设置的变量；可重复指定
• --env-file <path> — 从 .env 文件设置所有变量
• --secret、--no-secret — 标记为密钥（新变量默认：false）
• --build、--no-build — 在构建时可用（新变量默认：false）
• --runtime、--no-runtime — 在运行时可用（新变量默认：true）
• --json — 以 JSON 格式输出

之后请重新部署（运行时）或触发构建（构建时）——参见“限制”。

variables delete

按 ID（var_...）或键删除变量。此操作不可撤销；系统变量无法删除。

mcloud variables delete API_KEY \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle> \
  --yes

参数：

• variable — 要删除的变量 ID（var_...）或键（必填）

选项：

• -o/--organization <id>、-p/--project <id-or-handle>、-e/--environment <handle>
• -t/--type <backend|storefront> — 要删除变量的变量集（默认：backend）
• -y/--yes — 跳过确认提示（非交互模式下必需）
• --json — 以 JSON 格式输出

变量字段（JSON）

字段	描述
id	变量 ID（var_...）
key	变量名称（例如 ADMIN_CORS）
value	变量值（若 is_secret 为真且未传入 --reveal，则会被遮蔽）
is_secret	该变量是否被视为机密
is_build	在构建时可用
is_runtime	在运行时可用
environment_id	此变量所属的环境 ID
source	用户设置的变量为 user，自动注入的变量为 system

示例

# List all variables for the active environment
mcloud variables list --json

# List only runtime variables, including system ones
mcloud variables list --scope runtime --include-system --json

# List storefront variables
mcloud variables list --type storefront --json

# Get a variable by key (with active context)
mcloud variables get DATABASE_URL --json

# Get a variable by ID (no env context needed)
mcloud variables get var_01XYZ --json

# Set a single variable, then redeploy to apply (runtime)
mcloud variables set REDIS_URL redis://cache:6379
mcloud environments redeploy production

# Set a secret build-only variable, then trigger a build to apply
mcloud variables set STRIPE_SECRET_KEY sk_live_123 --secret --build --no-runtime
mcloud environments trigger-build production

# Set multiple variables from a .env file
mcloud variables set --env-file .env

# Delete a variable (irreversible — confirm before running)
mcloud variables delete OLD_FLAG --yes

# Only reveal secrets when user explicitly asks
mcloud variables get STRIPE_SECRET_KEY --reveal --json | jq -r '.value'

# Export all variables to a .env file (user must explicitly request --reveal)
mcloud variables list --reveal --dotenv > .env

# Check if a specific variable exists
mcloud variables list --json | jq '.[] | select(.key == "REDIS_URL")'