inngest-api-cli

Inngest API CLI

接続済みの MCP ツールを使った Cloud 操作には、まず inngest-cloud を使用してください。 このスキルは、明示的なターミナル/HTTP 作業や、MCP に欠けている機能のために取っておいてください。 OAuth MCP でタスクを完了できる場合は、API キーを要求しないでください。

このスキルは、タスクが運用上のものである場合に使用します。つまり、ターミナルを通じて Inngest API リソースを調査、デバッグ、同期、呼び出し、またはクエリする場合です。このスキルは、エージェントが推測せずに行動できるように、意図的に指示的になっています。

一般的な CLI のセットアップ、inngest dev、Docker、ローカルテスト、MCP のセットアップ、またはセルフホスト可能な inngest start については、inngest-cli を使用してください。コード変更については、コードパターンを担うドメインスキルと組み合わせてください: inngest-setup、inngest-durable-functions、inngest-events、inngest-steps、inngest-flow-control、inngest-realtime、または inngest-middleware。

最初の一手

記憶に頼る前に、現在の CLI のサーフェスを確認してください:

npx inngest-cli@latest api --help
npx inngest-cli@latest api <command> --help

有効な API コマンドは inngest api です。プロンプトのコンテキストや古いドキュメントに inngest alpha api と記載されている場合は、inngest api に切り替えてください。

inngest-api は次の場合にのみ使用してください:

• CLI が必要なエンドポイントを公開していない。
• ユーザーが生の REST API v2 を明示的に求めている。
• リクエストの形を解決するために OpenAPI スペックまたは LLM API ドキュメントが必要である。

完全なコマンドフラグについては、このスキルがトリガーされた後に references/cli-commands.md を参照してください。

ターゲットのルール

• inngest api のデフォルトターゲットはローカルです。
• Cloud Production には --prod が必要です。
• 非本番の Cloud 環境には INNGEST_ENV=<name> または --env が必要です。
• Cloud API アクセスには INNGEST_API_KEY を推奨します。
• ユーザーがプロセスリストやトランスクリプトへの露出を明示的に受け入れない限り、API キーを --api-key <secret> でインライン指定しないでください。
• API キー、イベントキー、署名キー、Webhook URL、復号されたシークレットを、ソースファイル、ドキュメント、フィクスチャ、最終回答に決して書き込まないでください。

一般的なターゲット:

npx inngest-cli@latest api health
npx inngest-cli@latest api --prod get-account
INNGEST_ENV=staging npx inngest-cli@latest api --prod get-webhooks
npx inngest-cli@latest api --api-host http://127.0.0.1 --api-port 8288 health

ローカル開発

ローカルアプリの作業では:

1. 該当する場合は、ユーザーのアプリをローカル開発モードで起動します。例えば INNGEST_DEV=1 npm run dev です。

2. 開発サーバーを起動します:

   npx inngest-cli@latest dev
   

3. 利用可能な場合は、Dev Server MCP ツールを優先して、ローカル関数の一覧表示、テストイベントの送信、 実行の検査、ステータスの監視を行います。

4. API 互換のローカルチェック、コマンドヘルプの検証、MCP を通じて公開されていない ワークフローには、npx inngest-cli@latest api ... を使用します。

ローカル API が開発サーバーを利用できないと報告する場合は、inngest dev を起動するか、ユーザーがデプロイ済みの実行をデバッグしているときは --prod で Cloud に切り替えてください。

コマンドルーティング

人間にさらにコンテキストを求める前に、この表を使用してください。

状況	コマンドパス
CLI/API の到達性を確認する	api health
Cloud 認証を確認する	api --prod get-account
環境を一覧表示する	api --prod get-account-envs --limit 10
イベントキーを一覧表示する	api --prod get-account-event-keys --limit 10
署名キーを一覧表示する	api --prod get-account-signing-keys --limit 10
Webhook を一覧表示する	api --prod get-webhooks
ユーザーが実行 ID を提示する	api --prod get-function-run <run_id>
ステップレベルの詳細が必要	api --prod get-function-trace <run_id> --include-output
ユーザーがイベント ID を提示する	api --prod get-event-runs <event_id> --limit 5 --include-output
既知のアプリ ID を同期する	api --prod sync-app --app-id <app_id> --url <serve_url>
既知のアプリ/関数 ID を呼び出す	api --prod invoke-function --app-id <app_id> --function-id <function_id> --data '<json>'
Insights テーブルを検出する	api --prod get-insights-tables
Insights のイベントスキーマを検出する	api --prod get-insights-event-schemas --limit 25
Insights クエリをドラフトする	api --prod query-insights-prompt --prompt '<request>'
Insights クエリを実行する	api --prod query-insights --query '<sql>'

コマンドが位置引数の ID を受け入れる場合は、例では位置引数の ID を優先してください。それらはより短く、現在のヘルプと一致するためです。--run-id のようなフラグ形式も、現在の CLI では多くのパスパラメータで受け入れられます。

実行のデバッグ

ユーザーが実行 ID を指定した場合:

npx inngest-cli@latest api --prod get-function-run <run_id>
npx inngest-cli@latest api --prod get-function-trace <run_id> --include-output

ステータス、失敗したスパン、リトライ状態、タイミング、エラー名/メッセージ、および調査すべき可能性の高いコード境界を要約します。依頼されない限り、トレース全体を貼り付けないでください。

ユーザーがイベント ID を指定した場合:

npx inngest-cli@latest api --prod get-event-runs <event_id> --limit 5 --include-output

レスポンスから該当する実行を選び、その実行とトレースを取得します。複数の実行が候補になる場合は、候補を説明し、タイムスタンプ、関数 ID、または失敗ステータスを使って選択してください。

ID が見つからない場合

すぐにユーザーへアプリ ID、関数 ID、実行 ID を尋ねないでください。

次の順序で試します:

1. 利用可能であれば、Dev Server MCP ツール。
2. ユーザーのプロンプト、貼り付けられたダッシュボード URL、ログ、アラート本文、またはスタックトレース。
3. リポジトリの設定と Inngest の serve 定義。
4. get-event-runs によるイベント ID の検索。
5. 現在の CLI ヘルプで、get-functions や get-app などの検出コマンドが追加されていないか確認。

これらの情報源から得られない場合にのみ、ユーザーに ID を尋ねてください。

変更操作

書き込みの前に読み取りを行います。まず該当するリソースを一覧表示または取得し、対象と意図が明確な場合にのみ変更を加えます。

ユーザーがすでにアカウント/環境と正確な意図を指定していない限り、Cloud に対してこれらを実行する前に確認してください:

• create-env
• patch-env
• create-webhook
• sync-app
• invoke-function
• 広範または高コストな query-insights 呼び出し

反復可能な呼び出しテストでは、安定した冪等性キーを使用します:

npx inngest-cli@latest api --prod invoke-function \
  --app-id <app_id> \
  --function-id <function_id> \
  --idempotency-key <stable_test_key> \
  --data '{"example":true}'

複雑な JSON には、引用符のミスを避けるため --body-file を使用します。

Insights

質問が分析的である場合、ログが部分的な手がかりしか与えない場合、またはユーザーが傾向、頻度、ボリューム、経時的な失敗、あるいはイベント/実行データについて尋ねる場合に Insights を使用します。

小さく始めます:

npx inngest-cli@latest api --prod get-insights-tables
npx inngest-cli@latest api --prod get-insights-event-schemas --limit 25
npx inngest-cli@latest api --prod query-insights-prompt \
  --prompt "Show failed functions in the last 24 hours"

広範なクエリを実行する前に、生成された SQL を確認します。可能な場合は制限と時間枠を追加してください。

出力の扱い

• CLI の出力は JSON です。判断を下す前に構造的にパースします。
• --raw は、下流のコマンドが正確なレスポンスボディを必要とする場合にのみ使用します。
• レスポンスがページ分割されており page.hasMore が true の場合、完全な結果が必要なときは --cursor で続行します。
• エラーが存在しない限り、リストレスポンスで data がない場合は空のリストとして扱います。
• 要約では、シークレット、Webhook URL、トークン値、および機密性の高いペイロードフィールドを伏せてください。

ドリフトの扱い

CLI はベータ版です。動作がこのスキルと異なる場合:

1. トップレベルおよびコマンド固有のヘルプを実行します。
2. https://api-docs.inngest.com/llms.txt を確認します。
3. https://api-docs.inngest.com/api-specs/v2.json を確認します。
4. 生の REST API へのフォールバックには inngest-api スキルを使用します。

一部のローンチ資料では get-run や invoke-function-by-slug などのエイリアスに言及している場合があります。これらは現在の api --help で公開されている場合にのみ使用してください。存在しない場合は、get-function-run と invoke-function を使用します。