makecli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

makecli — Make Platform CLI

makecli — Make 平台 CLI

makecli is the CLI for the Make agentic development platform. It manages Apps, Entities, Relations, Records, and code deployment.

makecli 是 Make 智能体开发平台的 CLI 工具，用于管理应用、实体、关系、记录以及代码部署。

Installation

安装

bash

brew tap qfeius/makecli
brew install makecli
makecli update          # self-update + sync Make platform skills

bash

brew tap qfeius/makecli
brew install makecli
makecli update          # self-update + sync Make platform skills

Pre-flight Check

前置检查

Before executing ANY makecli command, verify the environment:

Check
```
makecli
```
is installed — missing: run the installation above
Run
```
makecli configure verify --output=json
```
to check token status
- Not configured / expired: user must run
```
makecli login
```
  (browser OAuth)
- INTERACTIVE (opens browser, blocks) — instruct user to run it themselves via the
```
!
```
  shell prefix (supported by Claude Code and Codex)
- Fallback for manual tokens:
```
makecli configure token
```
  (also interactive, via
```
!
```
  )
Config errors mentioning stale keys → run
```
makecli doctor
```
(read-only report);
```
makecli doctor --fix
```
migrates them in place

Backend context defaults to

production

. Switch the global default with

makecli context use dev|test

, a profile default with

makecli configure set context <ctx>

, or per-call

--context

. Resolution order:

--context

$MAKE_CLI_CONTEXT

> profile

context

[settings] context

production

在执行任何 makecli 命令之前，请先验证环境：

检查
```
makecli
```
是否已安装——未安装则运行上述安装步骤
运行
```
makecli configure verify --output=json
```
检查 token 状态
- 未配置/已过期：用户必须运行
```
makecli login
```
  （浏览器 OAuth）
- 交互式（打开浏览器，会阻塞）——指导用户通过
```
!
```
  shell 前缀自行运行（Claude Code 和 Codex 支持）
- 手动 token 的替代方案：
```
makecli configure token
```
  （同样为交互式，通过
```
!
```
  运行）
配置错误提到过期密钥 → 运行
```
makecli doctor
```
（只读报告）；
```
makecli doctor --fix
```
可就地迁移修复

后端上下文默认为

production

。可通过

makecli context use dev|test

切换全局默认值，通过

makecli configure set context <ctx>

切换配置文件默认值，或在单次调用时使用

--context

参数。解析优先级：

--context

$MAKE_CLI_CONTEXT

环境变量 > 配置文件

context

[settings] context

production

。

Vocabulary: context vs environment

词汇表：context 与 environment

Two different axes — never mix them up:

Word	Meaning	Values	Where
context	which Make backend the CLI talks to	`dev` / `test` / `production`	global `--context` , profile `context` , `makecli context use` ( `[settings] context` )
environment	an app's deployment target	`beta` / `production`	local `--env` on `app delete` ; `app deploy` is beta-only, `app promote` is beta → production

Every app is a prod/beta pair on the server, both living in the same backend context.

app deploy

only ever pushes to beta (no

--env

). Production is reached only by

app promote

(beta → production) — there is no direct production push. Preserve the current profile and backend context through deploy, promote, and verification; check local command help before relying on flags from an older CLI.

两个完全不同的概念——切勿混淆：

词汇	含义	取值	作用位置
context	CLI 连接的 Make 后端	`dev` / `test` / `production`	全局 `--context` 、配置文件 `context` 、 `makecli context use` （ `[settings] context` ）
environment	应用的部署目标	`beta` / `production`	`app delete` 命令的本地 `--env` 参数； `app deploy` 仅支持 beta， `app promote` 用于 beta → production

每个应用在服务器上都是 prod/beta 成对存在 的，两者位于同一个后端上下文中。

app deploy

只会推送到 beta 环境（无

--env

参数）。只能通过

app promote

（beta → production）到达生产环境——不存在直接推送到生产环境的方式。在部署、升级和验证过程中请保持当前配置文件和后端上下文不变；在依赖旧版 CLI 的标志之前，请先查看本地命令帮助。

Decision Tree

决策树

User request arrives
    |
    +- makecli not installed / not logged in? --> Pre-flight Check above
    |
    +- New app project? --> app init (local scaffold) / app create (scaffold + register)
    |
    +- Create/update schema (entity, relation)?
    |   --> Declarative Workflow (preferred)
    |
    +- Deploy code to Beta (including recreate and deploy)? --> Deploy Code
    |
    +- Publish Beta to Prod / 发布到 prod 环境上? --> Promote Beta to Prod
    |
    +- Build/deploy progress? --> app deploy --status / --wait ; app promote --status --id <promoteId> / --wait
    |
    +- App overview + environment URLs? --> app info <appKey>
    |
    +- Data CRUD? --> record commands
    |
    +- Delete resource / one-off operation? --> Imperative Workflow
    |
    +- Query / inspect? --> list/get/schema commands

User request arrives
    |
    +- makecli not installed / not logged in? --> Pre-flight Check above
    |
    +- New app project? --> app init (local scaffold) / app create (scaffold + register)
    |
    +- Create/update schema (entity, relation)?
    |   --> Declarative Workflow (preferred)
    |
    +- Deploy code to Beta (including recreate and deploy)? --> Deploy Code
    |
    +- Publish Beta to Prod / 发布到 prod 环境上? --> Promote Beta to Prod
    |
    +- Build/deploy progress? --> app deploy --status / --wait ; app promote --status --id <promoteId> / --wait
    |
    +- App overview + environment URLs? --> app info <appKey>
    |
    +- Data CRUD? --> record commands
    |
    +- Delete resource / one-off operation? --> Imperative Workflow
    |
    +- Query / inspect? --> list/get/schema commands

Workflow: Declarative Schema (Primary)

工作流：声明式 Schema（主要方式）

When: Creating or updating schema resources (App, Entity, Relation). Why preferred: Reproducible, diffable, safe (preview before apply).

Write DSL YAML under
```
apps/dsl/
```
— invoke the
```
makedsl
```
skill for schema reference
Diff:
```
makecli diff -f apps/dsl
```
— preview changes against remote
Confirm diff output with user
Apply:
```
makecli apply -f apps/dsl
```

Verify:

makecli diff -f apps/dsl

(exit 0) or

makecli schema --app <appKey>

Key rules:

Entity/Relation: create if new, update if exists. App is create-only — apply never updates an existing App
diff exit code: 0 = no differences, 1 = differences found
Directory scan recurses into immediate subdirs by default (
```
--max-depth 2
```
, shared by diff/apply)

适用场景： 创建或更新 schema 资源（应用、实体、关系）。 为何推荐： 可复现、可对比差异、安全（apply 前可预览）。

编写
```
apps/dsl/
```
目录下的 DSL YAML——调用
```
makedsl
```
技能获取 schema 参考
差异对比：
```
makecli diff -f apps/dsl
```
——预览与远程环境的差异
与用户确认 diff 输出
应用：
```
makecli apply -f apps/dsl
```

验证：

makecli diff -f apps/dsl

（退出码 0）或

makecli schema --app <appKey>

核心规则：

实体/关系：新建则创建，已存在则更新。应用仅支持创建——apply 永远不会更新已有的应用
diff 退出码：0 = 无差异，1 = 存在差异
默认情况下目录扫描会递归到直接子目录（
```
--max-depth 2
```
，diff 和 apply 共享此行为）

Workflow: Deploy Code

工作流：部署代码

bash

makecli preflight                      # validate against the build spec (build mode auto-detected)
git add -A && git commit -m "..."      # deploy pushes committed HEAD; dirty worktree is refused
makecli app deploy --context <context> --profile <profile> --wait  # push committed HEAD to Beta + block until terminal state

Deploy reads the app key from

apps/dsl/app.yaml

and refuses apps never registered via

app create

--wait
is the agent-friendly path — one call, one verdict:

Exit code 0 = build SUCCESS (environment URL printed as
```
URL:
```
row) / 2 = build FAILED or CANCELED (error detail printed) / 124 = timeout (
```
--timeout
```
, default 5m; build may still be running)
Re-running after a timeout re-attaches to the same build (keyed by HEAD commit sha) — it's idempotent

Check progress without pushing:

bash

makecli app deploy --status                # one-shot snapshot of the current HEAD's deploy status
makecli app deploy --status --output json  # machine-readable (BuildTask fields + url on success)
makecli app deploy --status --wait         # block until terminal state, no push

bash

makecli preflight                      # validate against the build spec (build mode auto-detected)
git add -A && git commit -m "..."      # deploy pushes committed HEAD; dirty worktree is refused
makecli app deploy --context <context> --profile <profile> --wait  # push committed HEAD to Beta + block until terminal state

部署会从

apps/dsl/app.yaml

读取应用 key，并且拒绝部署从未通过

app create

注册的应用。

--wait
是对 Agent 友好的方式——一次调用，一个结果：

退出码 0 = 构建成功（环境 URL 会以
```
URL:
```
行的形式打印）/ 2 = 构建失败或已取消（会打印错误详情）/ 124 = 超时（
```
--timeout
```
，默认 5 分钟；构建可能仍在运行）
超时后重新运行会重新关联到同一个构建（以 HEAD 提交的 sha 为键）——具有幂等性

无需推送即可检查进度：

bash

makecli app deploy --status                # one-shot snapshot of the current HEAD's deploy status
makecli app deploy --status --output json  # machine-readable (BuildTask fields + url on success)
makecli app deploy --status --wait         # block until terminal state, no push

Beta deployment result and next step

Beta 部署结果与后续步骤

Apply this completion flow to every successful Beta deployment, including a user-authorized recreate-and-deploy flow:

Verify
```
app info <appKey>
```
in the same context/profile reports Beta
```
Ready
```
for the deployed commit. Report the Beta URL, build/commit, and checks actually completed; keep authenticated browser acceptance separate.
Offer 发布到 prod 环境上 as the next step. In Codex clients that support follow-up actions, emit the following as a Markdown list item outside a code fence. Replace every placeholder with the verified non-secret value before emitting it:

markdown

- :codex-followup[发布到 prod 环境上]{prompt="将应用 <appKey> 在 backend context <context>、profile <profile> 下刚完成的 Beta 构建 <buildId>（commit <commitSha>）发布到同一 context 的 Prod 环境。先核对 Beta 仍是该构建，若已变化则说明差异并等待确认；发布后验证 Prod Ready、健康接口和统一登录响应。"}

In clients without follow-up actions, say:

如需发布当前 Beta 版本到正式环境，请输入“发布到 prod 环境上”。

Showing the guide does not authorize promotion. A submitted follow-up or an explicit equivalent request does; proceed without asking for the same permission again.
Do not show the guide for pending/failed deployments, after successful promotion of this release, or when the same Beta code and Console configuration are already confirmed published. Matching commit SHAs alone cannot rule out unpublished Console changes. If Prod publication is already authorized, continue to promotion instead of offering the guide.

每次成功的 Beta 部署都应遵循此完成流程，包括用户授权的重建并部署流程：

在相同的上下文/配置文件中验证
```
app info <appKey>
```
显示 Beta 对已部署的提交处于
```
Ready
```
状态。报告 Beta URL、构建/提交信息，以及实际完成的检查项；将已认证的浏览器验收单独处理。
提供 发布到 prod 环境上 作为下一步操作。在支持后续操作的 Codex 客户端中，将以下内容作为 Markdown 列表项输出在代码块之外。输出前请将每个占位符替换为已验证的非敏感值：

markdown

- :codex-followup[发布到 prod 环境上]{prompt="将应用 <appKey> 在 backend context <context>、profile <profile> 下刚完成的 Beta 构建 <buildId>（commit <commitSha>）发布到同一 context 的 Prod 环境。先核对 Beta 仍是该构建，若已变化则说明差异并等待确认；发布后验证 Prod Ready、健康接口和统一登录响应。"}

在不支持后续操作的客户端中，提示：

如需发布当前 Beta 版本到正式环境，请输入“发布到 prod 环境上”。

显示指南并不等同于授权发布。提交的后续操作或明确的等效请求才是授权；无需再次请求相同的权限。
对于待处理/失败的部署、此版本成功升级后，或当相同的 Beta 代码 和控制台配置 已确认发布时，请勿显示此指南。仅匹配提交 SHA 无法排除未发布的控制台变更。如果已授权生产发布，请直接继续升级流程，而不是提供指南。

Workflow: Promote Beta to Prod

工作流：将 Beta 升级到 Prod

app promote

publishes Beta's Console configuration and last successful deployment commit to the paired Prod App. It pushes no local code. A request such as 发布到 prod 环境上 after Beta deployment selects this workflow and keeps the same backend context/profile; changing the backend context is a separate user request.

Read
```
makecli app promote --help
```
and refresh
```
app info <appKey>
```
in the established context/profile. Confirm the Beta source is Ready; if a follow-up names a build that has changed, report the difference and obtain confirmation for the new source. If the installed CLI lacks
```
promote
```
, report the limitation rather than guessing a legacy command.
With the user's explicit production authorization, run from the App project directory:

bash

makecli app promote --context <context> --profile <profile> --yes --wait

If the wait times out, retain the promote ID and resume the same run with
```
app promote --status --id <promoteId> --wait
```
in the same context/profile. Do not start a duplicate promotion to check progress.
Verify
```
app info <appKey>
```
reports Prod
```
Ready
```
and the expected commit, then check the Prod URL and applicable health/auth endpoints. Report the Prod URL, build/commit, backend context, and any unverified browser acceptance. On failure, report the failed step and error without claiming publication succeeded.

See CLI reference for promote status flags and exit codes.

app promote

会将 Beta 的控制台配置和最后一次成功部署的提交发布到配对的 Prod 应用。它不会推送本地代码。Beta 部署后类似 发布到 prod 环境上 的请求会选择此工作流，并保持相同的后端上下文/配置文件；更改后端上下文是单独的用户请求。

查看
```
makecli app promote --help
```
并在已建立的上下文/配置文件中刷新
```
app info <appKey>
```
。确认 Beta 源处于 Ready 状态；如果后续操作指定的构建已发生变化，报告差异并获取对新源的确认。如果安装的 CLI 没有
```
promote
```
命令，请报告此限制，而不是猜测旧版命令。
获得用户明确的生产授权后，在应用项目目录中运行：

bash

makecli app promote --context <context> --profile <profile> --yes --wait

如果等待超时，保留升级 ID，并在相同的上下文/配置文件中使用
```
app promote --status --id <promoteId> --wait
```
恢复同一次运行。请勿启动重复的升级来检查进度。
验证
```
app info <appKey>
```
显示 Prod 处于
```
Ready
```
状态且提交符合预期，然后检查 Prod URL 和适用的健康/认证端点。报告 Prod URL、构建/提交、后端上下文，以及任何未验证的浏览器验收。如果失败，报告失败的步骤和错误，不要声称发布成功。

参见 CLI 参考了解升级状态标志和退出码。

Workflow: Imperative Operations

工作流：命令式操作

When: Single deletions, data CRUD, or operations not covered by apply.

Read

@references/cli-reference.md

for exact flag syntax and JSON file formats.

bash

undefined

适用场景： 单次删除、数据 CRUD，或 apply 未覆盖的操作。

请阅读

@references/cli-reference.md

了解准确的标志语法和 JSON 文件格式。

bash

undefined

App

makecli app create <appKey> [--name <display>] [--description <desc>] [--dry-run] makecli app delete <key> --env beta|production|ALL --yes # --env required; confirmation prompt without --yes makecli app list [--filter "name=待办,key=todo"] [--output json]

Entity / Relation (require --app)

makecli entity create <key> --app <app> [--name <display>] [--json props.json] [--dry-run] makecli entity list [<key>] --app <app> makecli relation create <key> --app <app> --json rel.json [--dry-run]

Record (require --app + --entity; JSON = flat field map)

makecli record create --app <app> --entity <entity> --json data.json [--dry-run] makecli record list --app <app> --entity <entity> --filter "status in ['todo'] && owner == _currentUser" [--sort-json '[{"fieldKey":"createdAt","order":"desc"}]'] makecli record aggregate --app <app> --entity <entity> --group-json '[{"fieldKey":"status"}]' --aggregates-json '[{"aggregate":"count","alias":"n"}]' # server-side GROUP BY makecli record update <id> [id...] --app <app> --entity <entity> --json data.json makecli record delete <id> [id...] --app <app> --entity <entity>


All create commands accept `--dry-run` — server validates without persisting.


所有 create 命令都支持 `--dry-run`——服务器会进行验证但不会持久化。

Configuration

配置

bash

undefined

bash

undefined

Step 1: Authenticate (INTERACTIVE -- user must run via !)

! makecli login # browser OAuth; manual fallback: configure token

Step 2: Global settings ([settings] section, shared by every profile)

makecli context use test # global default backend context (= settings set context test) makecli settings set channel beta # release channel stable|beta for

makecli update

makecli settings list # every global key with value + source

makecli context use test # global default backend context (= settings set context test) makecli settings set channel beta # release channel stable|beta for

makecli update

makecli settings list # every global key with value + source

Step 3: Per-profile overrides (only if non-default)

makecli configure set context test # backend default for the current profile (beats [settings] context) makecli configure set meta-server-url <host> # host only, /api/make auto-added makecli configure set X-Tenant-ID <tenant> makecli configure set X-Operator-ID <operator> makecli configure --sample # print full config reference

Verify

makecli doctor # local config health check (exit 1 on problems; --fix for safe repairs) makecli configure verify --output=json makecli configure resolve --target local-preview --output=json


`configure` manages **profile** keys (`context`, `meta-server-url`, `repo-server-url`, `auth-server-url`, `X-Tenant-ID`, `X-Operator-ID`); `settings` manages **global** keys (`context`, `channel`, `role`, `check-for-updates`). `context` exists at both levels — the profile value wins over the global one. Other keys sent to the wrong command are refused with a pointer to the right one. The `--context` flag overrides both for one command; it selects the backend only, never the App's Beta/Prod environment.

For local preview, use `configure resolve --target local-preview --output=json` as the primary source of the effective public Make origin. Consume `make_api_origin` as a bare origin and let the local-preview Service add the browser-facing `/api/make` scope. Profile-specific host overrides such as `meta-server-url` and `repo-server-url` should be origins; path-scoped legacy values must be normalized before adapter URL construction.

`--context` / `--env` belong on the specific `makecli` command being executed; do not route them through project-local package scripts such as `corepack pnpm run verify:publish -- --context dev`. New Make Apps and explicit runtime migrations use the `make-app-runtime` runtime baseline (Node.js `22.20.0`, Corepack `0.34.0`, and `pnpm@10.20.0` through Corepack); ordinary deployment work must not rewrite an existing App's runtime declaration. Run the project gate before `makecli app deploy --wait` to Beta. After explicit production authorization, use `makecli app promote --yes --wait` in the same context/profile.

**Profiles:** All commands accept `--profile <name>` (default: "default").
**Config files:** `~/.make/credentials` and `~/.make/config` (INI format).

makecli doctor # local config health check (exit 1 on problems; --fix for safe repairs) makecli configure verify --output=json makecli configure resolve --target local-preview --output=json


`configure` 管理 **配置文件（profile）** 级别的键（`context`、`meta-server-url`、`repo-server-url`、`auth-server-url`、`X-Tenant-ID`、`X-Operator-ID`）；`settings` 管理 **全局** 级别的键（`context`、`channel`、`role`、`check-for-updates`）。`context` 在两个级别都存在——配置文件的值优先于全局值。发送到错误命令的其他键会被拒绝，并提示正确的命令。`--context` 标志会在单次命令中覆盖这两个级别；它仅选择后端，永远不会更改应用的 Beta/Prod 环境。

对于本地预览，请使用 `configure resolve --target local-preview --output=json` 作为有效公共 Make 源的主要来源。将 `make_api_origin` 用作裸源，并让本地预览服务添加面向浏览器的 `/api/make` 作用域。特定于配置文件的主机覆盖（如 `meta-server-url` 和 `repo-server-url`）应为源地址；路径作用域的旧值必须在构建适配器 URL 之前进行规范化。

`--context` / `--env` 应放在正在执行的具体 `makecli` 命令上；不要通过项目本地的 package 脚本（如 `corepack pnpm run verify:publish -- --context dev`）传递它们。新的 Make 应用和显式运行时迁移使用 `make-app-runtime` 运行时基线（Node.js `22.20.0`、Corepack `0.34.0`，以及通过 Corepack 安装的 `pnpm@10.20.0`）；常规部署工作不得重写现有应用的运行时声明。在 `makecli app deploy --wait` 部署到 Beta 之前运行项目门禁。在获得明确的生产授权后，在相同的上下文/配置文件中使用 `makecli app promote --yes --wait`。

**配置文件：** 所有命令都支持 `--profile <name>`（默认值："default"）。
**配置文件路径：** `~/.make/credentials` 和 `~/.make/config`（INI 格式）。

Account Self Inspect

账户自检

makecli whoami

makecli whoami

Common Patterns

常用模式

From zero to production:

bash

! makecli login                                   # 1. Authenticate (user runs via !)
makecli app create shop --name "我的商城"          # 2. Scaffold + register + initial commit
cd shop                                           # 3. Write DSL (makedsl skill) under apps/dsl/
makecli diff -f apps/dsl && makecli apply -f apps/dsl
git add -A && git commit -m "feat: initial app"   # 4. Develop, then commit
makecli app deploy --wait                         # 5. Deploy to Beta, wait for build, get URL
makecli app promote --wait                        # 6. Verified in Beta + user authorized? Publish it to Prod (confirm)

Inspect remote state:

bash

makecli app list --filter "key=shop"
makecli app info <appKey>                 # app meta + beta/production deploy status & URLs
makecli entity list --app <app>
makecli entity list <key> --app <app>     # detail view: fields + unique constraints
makecli schema --app <app>                # aggregated app + entities + relations

从零到生产：

bash

! makecli login                                   # 1. Authenticate (user runs via !)
makecli app create shop --name "我的商城"          # 2. Scaffold + register + initial commit
cd shop                                           # 3. Write DSL (makedsl skill) under apps/dsl/
makecli diff -f apps/dsl && makecli apply -f apps/dsl
git add -A && git commit -m "feat: initial app"   # 4. Develop, then commit
makecli app deploy --wait                         # 5. Deploy to Beta, wait for build, get URL
makecli app promote --wait                        # 6. Verified in Beta + user authorized? Publish it to Prod (confirm)

检视远程状态：

bash

makecli app list --filter "key=shop"
makecli app info <appKey>                 # app meta + beta/production deploy status & URLs
makecli entity list --app <app>
makecli entity list <key> --app <app>     # detail view: fields + unique constraints
makecli schema --app <app>                # aggregated app + entities + relations

Anti-Patterns

反模式

Don't skip diff before apply. Always preview changes first.
Don't use imperative commands for bulk schema setup. Use YAML + apply instead.
Don't guess CLI flags. Read
```
@references/cli-reference.md
```
if unsure.
Don't run interactive commands via Bash tool.
```
login
```
,
```
configure token
```
,
```
configure config
```
block on user input — tell user to run via
```
!
```
.
Don't pass
--yes
to
app delete
or
app promote
without explicit user consent. These flags skip safety confirmations.
Don't promote before beta is deployed and verified.
```
app promote
```
publishes the server's beta state, not your local code.
Don't deploy with a dirty worktree.
```
app deploy
```
pushes committed HEAD only — commit first, it never auto-commits.

Don't hand-roll polling loops over
--status
. Use

deploy --status --wait

promote --status --id <promoteId> --wait

Don't write DSL YAML from memory. Invoke the
```
makedsl
```
skill for schema reference.

不要在 apply 之前跳过 diff。 务必先预览变更。
不要使用命令式命令进行批量 schema 设置。 请改用 YAML + apply。
不要猜测 CLI 标志。 如果不确定，请阅读
```
@references/cli-reference.md
```
。
不要通过 Bash 工具运行交互式命令。
```
login
```
、
```
configure token
```
、
```
configure config
```
会因用户输入而阻塞——告知用户通过
```
!
```
运行。
未经用户明确同意，不要向
app delete
或
app promote
传递
--yes
。这些标志会跳过安全确认。
不要在 beta 部署并验证之前升级。
```
app promote
```
发布的是服务器上的 beta 状态，而不是你的本地代码。
不要在工作树未提交的情况下部署。
```
app deploy
```
仅推送已提交的 HEAD——请先提交，它永远不会自动提交。

不要手动编写基于
--status
的轮询循环。请使用

deploy --status --wait

promote --status --id <promoteId> --wait

。

不要凭记忆编写 DSL YAML。 请调用
```
makedsl
```
技能获取 schema 参考。