qfeius/make-platform-skills

makecli

Use when the user asks to manage Make platform resources with makecli — create/deploy apps, promote beta to production, check build/deploy progress or app URLs, read build/deployment logs, entities, relations, records, inspect resources, switch backend cont…

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/qfeius/make-platform-skills --skill makecli

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

makecli — Make Platform CLI

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

Installation

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:

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

Keep backend context separate from the app's role and deployment environment:

WordMeaningValuesWhere
contextwhich Make backend the CLI talks todev / test / productionglobal --context, profile context, makecli context use ([settings] context)
appRolewhich half of an app pair a command targetsbeta / prod (all for deletion)logs deploy --appRole defaults to beta; app delete --appRole is required
environmentan app's deployment targetbeta / productionapp 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.

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
    |
    +- 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

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

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

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

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:
bash
makecli app promote --context <context> --profile <profile> --yes --wait
  1. 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.
  2. 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: Read Build and Deployment Logs

Use logs deploy for build output and deployment lifecycle events. Application runtime and audit logs are outside this command's scope. Check makecli logs deploy --help first; if the installed CLI lacks the command or required flags, report that limitation.

bash
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 and commit default to apps/dsl/app.yaml and Git HEAD; --appRole defaults to beta. For a specific deployment, use its full commit SHA and preserve its backend context/profile. A follow reads until the selected stage completes or the total timeout expires; after a timeout, keep the same SHA and app role when retrying.

JSON snapshots report the selected beta or prod role in appRole.

Exit 0 means the logs were read successfully, including logs of failed deployments. Use app deploy --status or app promote --status --id <promoteId> to determine the deployment result.

See logs deploy reference for stages, tail, cursors, output, 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.

bash
# 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>

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

app delete waits for the final deletion result (default --timeout 30m). With --appRole all, it waits for Beta to succeed before deleting Prod. If waiting times out, the remote task may still be running; retry in the same context/profile. A retry joins a running deletion, and all skips Beta if its deletion already succeeded. See app delete reference for failure and retry behavior.

Configuration

bash
# 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 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 belongs on the specific makecli command being executed; do not route it 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

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

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.
do mesmo repositório

Mais Skills

Todos os Skills
qfeius
Comunidade

make-app-filter

Use when generating, integrating, reviewing, or debugging Make App record-list keyword search through Service filter.expression or advanced/conditional/table/header filtering with @qfei-design/make-app-filter. Triggered by 列表搜索, 关键词搜索, 筛选, 高级筛选, 条件筛选, 表格/表头/列头/按字段筛选, CEL/DNF, field-type operators, candidate values, and filter Preset save/echo. In search-only mode, use the package compiler without a filter panel or Preset lifecycle. In advanced-filter mode, use the package panel, permission-aware

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-observability

Use when creating, integrating, reviewing, or debugging a Make App's default Trace ID chain, traceparent and X-Log-Id propagation, safe correlated logs, or @qfei-design/make-app-observability error notices. Every new Make App includes this baseline even when the user does not mention observability. Covers direct-gateway and Service-fronted Apps and AI transports when present. Does not own authentication, Service route design, AI protocol, tracing backend/exporter deployment, runtime packaging, o

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-runtime

Use when generating, refactoring, reviewing, or debugging Make App project runtime structure, workspace manifests, Service runtime, local/dev scripts, build outputs, Docker/K8s image entrypoints, publish readiness, or packaging errors such as missing apps/service/dist/server.js. Covers apps/ workspace contracts, apps/ui/dist, apps/service port/build/start contracts, runtime config file location, runtime artifact tests, forwarded host/proto header preservation, and publish gates that include auth

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-service

Use when generating, refactoring, reviewing, or debugging Make App apps/service APIs and UI-Service contracts, including server-side aggregation for dashboards, charts and 统计/汇总. Covers route design, apps/docs/api.md, layered structure, Make adapters, direct Make response passthrough, schema normalization including independent fields/createFields collections, record CRUD, record-write-permission and records/bulk, list filter/sort/groupFilter parsing, record groups, Entity Preset, candidate/looku

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.