makecli

makecli — Make Platform CLI

makecli は Make エージェント型開発プラットフォームの 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）
   • 対話型（ブラウザーを開き、処理がブロックされます）— ユーザー自身が ! シェルプレフィックスを使って実行するよう案内してください（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

バックエンドのコンテキストと、アプリの役割およびデプロイ環境を区別してください。

用語	意味	値	使用箇所
context	CLI が接続する Make バックエンド	dev / test / production	グローバルな --context、プロファイルの context、makecli context use（[settings] context）
appRole	コマンドの対象となるアプリペアの側	beta / prod（削除時は all）	logs deploy --appRole のデフォルトは beta、app delete --appRole は必須
environment	アプリのデプロイ先	beta / production	app deploy は beta 専用、app promote は beta → production

サーバー上のすべてのアプリは prod/beta ペアであり、両方とも同じバックエンドコンテキストに属します。app deploy がプッシュする先は常に beta です（--env はありません）。production へ移行するには app promote のみを使用します（beta → production）。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 create で登録されていないアプリは拒否します。

--wait はエージェントに適した方法です — 1 回の呼び出しで結果が確定します。

• 終了コード 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 とコミットのデフォルトは、それぞれ apps/dsl/app.yaml と Git HEAD です。--appRole のデフォルトは beta です。特定のデプロイを対象にする場合は、完全なコミット SHA を使用し、そのバックエンドコンテキスト／プロファイルを維持します。follow は、選択したステージが完了するか、合計タイムアウトに達するまで読み取りを続けます。タイムアウト後に再試行する場合は、同じ SHA と App ロールを使用してください。

JSON スナップショットでは、選択した beta または prod ロールが appRole に報告されます。

終了コード 0 は、失敗したデプロイのログも含め、ログの読み取りに成功したことを意味します。デプロイ結果の確認には app deploy --status または app promote --status --id <promoteId> を使用してください。

ステージ、tail、カーソル、出力、終了コードについては、logs deploy リファレンスを参照してください。

ワークフロー：命令型操作

対象： 単一の削除、データの CRUD、または apply では対応できない操作。

正確なフラグの構文と JSON ファイル形式については、@references/cli-reference.md を参照してください。

# 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 の場合、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 フラグは、1 つのコマンドに限り両方の値を上書きします。これはバックエンドのみを選択し、App の Beta／Prod 環境は選択しません。

ローカルプレビューでは、実効的な公開 Make オリジンの主な情報源として configure resolve --target local-preview --output=json を使用してください。make_api_origin はオリジンのみとして扱い、ブラウザー向けの /api/make スコープは local-preview Service に追加させてください。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 のランタイム宣言を書き換えないでください。Beta に対して makecli app deploy --wait を実行する前に、プロジェクトのゲートを実行してください。明示的な本番環境への承認後は、同じコンテキスト／プロファイルで 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

アンチパターン

• apply の前に diff を省略しないでください。 必ず最初に変更をプレビューしてください。
• スキーマを一括設定するのに命令型コマンドを使わないでください。 代わりに YAML + apply を使用してください。
• CLI フラグを推測しないでください。 不明な場合は @references/cli-reference.md を参照してください。
• Bash ツール経由で対話型コマンドを実行しないでください。 login、configure token、configure config はユーザー入力を求めて停止します。ユーザーに ! 経由で実行するよう伝えてください。
• ユーザーの明示的な同意なしに、app delete または app promote に --yes を渡さないでください。 これらのフラグは安全確認をスキップします。
• Beta がデプロイされ、検証される前に promote しないでください。 app promote が公開するのはサーバー上の Beta の状態であり、ローカルコードではありません。
• 未コミットの変更がある状態でデプロイしないでください。 app deploy がプッシュするのはコミット済みの HEAD のみです。先にコミットしてください。自動コミットは行われません。
• --status を使ったポーリングループを独自に作成しないでください。 deploy --status --wait／promote --status --id <promoteId> --wait を使用してください。
• 記憶だけで DSL YAML を作成しないでください。 スキーマのリファレンスには makedsl スキルを呼び出してください。