makecli

makecli — Make Platform CLI

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

Installation

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:

0. Check makecli is installed — missing: run the installation above
1. 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 !)
2. 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.

Vocabulary: context vs environment

Two different axes — never mix them up:

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.

Decision Tree

Workflow: Declarative Schema (Primary)

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

1. Write DSL YAML under apps/dsl/ — invoke the makedsl skill for schema reference
2. Diff: makecli diff -f apps/dsl — preview changes against remote
3. Confirm diff output with user
4. Apply: makecli apply -f apps/dsl
5. 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)

Workflow: Deploy Code

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:

Beta deployment result and next step

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:

• 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.

Workflow: Promote Beta to 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.

1. 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.
2. With the user's explicit production authorization, run from the App project directory:

3. 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.
4. 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.

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.

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

Configuration

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

Account Self Inspect

Common Patterns

From zero to production:

Inspect remote state:

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.