makecli

makecli — Make 平台 CLI

makecli 是 Make Agent 化开发平台的 CLI。 它可管理 App、Entity、Relation、Record、代码部署以及构建／部署日志。

安装

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

预检

执行任何 makecli 命令前，请先检查环境：

0. 检查是否已安装 makecli——如果未安装，请运行上方的安装命令
1. 运行 makecli configure verify --output=json 检查令牌状态
   • 未配置或已过期：用户必须运行 makecli login（浏览器 OAuth）
   • 交互式（会打开浏览器并阻塞）——请指示用户通过 ! shell 前缀自行运行（Claude Code 和 Codex 支持）
   • 手动令牌的备用方式：makecli configure token（同样是交互式，通过 ! 运行）
2. 配置错误中提到过时的键时 → 运行 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。

词汇：context 与 environment

请将后端上下文与 App 的角色和部署环境区分开：

术语	含义	取值	位置
context	CLI 所连接的 Make 后端	dev / test / production	全局 --context、配置文件 context、makecli context use（[settings] context）
appRole	命令所针对的 App 配对中的一端	beta / prod（删除时为 all）	logs deploy --appRole 默认为 beta；app delete --appRole 为必填项
environment	App 的部署目标	beta / production	app deploy 仅支持 beta；app promote 为 beta → production

服务器上的每个 App 都是一个 prod/beta 配对，两者都位于同一后端上下文中。app deploy 只会推送到 beta（没有 --env）。只能通过 app promote（beta → production）部署到生产环境——不支持直接推送到生产环境。部署、晋升和验证过程中，请保留当前配置文件和后端上下文；使用旧版 CLI 中的标志前，请先查看本地命令帮助。

决策树

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
    |
    +- Build output / deployment lifecycle logs? --> Read Build and Deployment Logs
    |
    +- App overview + environment URLs? --> app info <appKey>
    |
    +- Data CRUD? --> record commands
    |
    +- Delete resource / one-off operation? --> Imperative Workflow
    |
    +- Query / inspect? --> list/get/schema commands

工作流：声明式架构（首选）

适用场景： 创建或更新架构资源（App、Entity、Relation）。 优先原因： 可复现、可比较差异且安全（应用前可预览）。

1. 编写： 在 apps/dsl/ 下编写 DSL YAML——架构参考请调用 makedsl 技能
2. 比较差异： makecli diff -f apps/dsl——预览与远程端相比的变更
3. 确认： 与用户确认差异输出
4. 应用： makecli apply -f apps/dsl
5. 验证： makecli diff -f apps/dsl（退出码为 0）或 makecli schema --app <appKey>

关键规则：

• Entity/Relation：不存在时创建，已存在时更新。App 仅支持创建——apply 永远不会更新现有 App
• diff 退出码：0 = 无差异，1 = 存在差异
• 默认递归扫描目录的第一层子目录（--max-depth 2，diff/apply 共用）

工作流：部署代码

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 读取 App 键，并拒绝部署从未通过 app create 注册的 App。

--wait 是适合 Agent 的方式——一次调用，一次判定：

• 退出码 0 = 构建成功（环境 URL 会以 URL: 行打印）/ 2 = 构建失败或已取消（会打印错误详情）/ 124 = 超时（--timeout，默认为 5m；构建可能仍在运行）
• 超时后重新运行会重新连接到同一构建（按 HEAD 提交 sha 标识）——操作具有幂等性

不推送代码即可检查进度：

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 部署结果和下一步

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

• 在相同的上下文/配置文件中验证 app info <appKey>，确认已部署的提交对应的 Beta 状态为 Ready。报告 Beta URL、构建/提交，以及实际完成的检查；将需要身份验证的浏览器验收单独说明。
• 提供 发布到 prod 环境上 作为下一步。在支持后续操作的 Codex 客户端中，将以下内容作为 Markdown 列表项输出，且不要放入代码围栏。输出前，将每个占位符替换为已验证的非机密值：

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

• 在不支持后续操作的客户端中，请说：如需发布当前 Beta 版本到正式环境，请输入“发布到 prod 环境上”。
• 展示指南不代表授权发布。用户提交后续操作或提出明确的等效请求，即表示已授权；无需再次询问相同权限。
• 对待处理/失败的部署、此版本成功发布之后，或已确认相同的 Beta 代码和 Console 配置均已发布的情况，不要展示指南。仅匹配提交 SHA 无法排除尚未发布的 Console 更改。如果已获准发布 Prod，请直接继续发布，而不是提供指南。

工作流：将 Beta 发布到 Prod

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

1. 阅读 makecli app promote --help，并在已建立的上下文/配置文件中刷新 app info <appKey>。确认 Beta 源状态为 Ready；如果后续操作指定的构建已发生变化，请说明差异，并就新的源版本征求确认。如果已安装的 CLI 不支持 promote，请说明此限制，不要猜测旧版命令。
2. 获得用户明确的生产环境授权后，在 App 项目目录中运行：

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

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

有关发布状态标志和退出代码，请参阅 CLI 参考。

工作流：读取构建和部署日志

使用 logs deploy 查看构建输出和部署生命周期事件。应用运行时日志和审计日志不在此命令的范围内。先检查 makecli logs deploy --help；如果已安装的 CLI 不支持该命令或所需标志，请说明此限制。

makecli logs deploy --stage all --tail 100 -f --timeout 3m
makecli logs deploy --appRole prod --commit-sha <fullSHA> --stage deploy
makecli logs deploy --app <appKey> --commit-sha <fullSHA> --output json

App 和 commit 默认分别为 apps/dsl/app.yaml 和 Git HEAD；--appRole 默认为 beta。对于特定部署，请使用完整的 commit SHA，并保留其后端上下文/配置文件。跟随读取会持续进行，直到所选阶段完成或总超时时间到期；超时后重试时，请保留相同的 SHA 和 app role。

JSON 快照会在 appRole 中报告所选的 beta 或 prod 角色。

退出代码 0 表示日志读取成功，包括失败部署的日志。使用 app deploy --status 或 app promote --status --id <promoteId> 确定部署结果。

有关阶段、tail、游标、输出和退出代码，请参阅 logs deploy 参考。

工作流：命令式操作

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

请阅读 @references/cli-reference.md，了解准确的标志语法和 JSON 文件格式。

# App
makecli app create <appKey> [--name <display>] [--description <desc>] [--dry-run]
makecli app delete <key> --appRole beta|prod|all  # required; confirmation prompt unless --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>

所有创建命令都接受 --dry-run——服务器会进行验证，但不会持久化。

app delete 会等待最终删除结果（默认 --timeout 30m）。使用 --appRole all 时，会等待 Beta 删除成功后再删除 Prod。如果等待超时，远程任务可能仍在运行；请在相同的上下文/配置文件中重试。重试会加入正在运行的删除任务；如果 Beta 已删除成功，all 会跳过 Beta。有关失败和重试行为，请参阅 app delete 参考。

配置

# 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

# 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 管理配置文件键（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 标志会覆盖这两个级别的值，仅对单条命令生效；它只选择后端，不会选择 App 的 Beta/Prod 环境。

对于本地预览，请使用 configure resolve --target local-preview --output=json 作为有效公共 Make 来源的主要依据。将 make_api_origin 作为纯来源使用，并由本地预览 Service 添加面向浏览器的 /api/make 路径范围。配置文件专属的主机覆盖项（例如 meta-server-url 和 repo-server-url）应为来源；在构建适配器 URL 之前，必须先规范化带路径的旧版值。

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

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

账户自检

makecli whoami

常见模式

从零开始部署到生产环境：

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

检查远程状态：

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

反模式

• 不要跳过 diff，直接执行 apply。 始终先预览更改。
• 不要使用命令式命令批量设置架构。 请改用 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 技能查阅架构参考。