inngest-cli

Inngest CLI

ローカル開発、テスト、セルフホスト型の本番環境で Inngest CLI を使いこなしましょう。CLI には Dev Server が用意されています。これは、Inngest Platform の機能をすべて備えたオープンソースのローカル版です。

これらのスキルは TypeScript に特化しています。 Python または Go については、言語固有のガイダンスが記載されている Inngest ドキュメントを参照してください。基本概念はすべての言語に共通です。

CLI のセットアップ、Dev Server のワークフロー、ローカルテスト、Docker、MCP、セルフホスト型サーバーの運用には、このスキルを使用してください。inngest api を使った実行／トレースの確認には、利用可能な場合は inngest-api-cli を使用してください。

インストール

# npx (recommended — always latest)
npx inngest-cli@latest dev

# yarn
yarn dlx inngest-cli@latest dev

# pnpm
pnpm dlx inngest-cli@latest dev

# Global install
npm install -g inngest-cli

# Docker
docker pull inngest/inngest

npm の設定でライフサイクルスクリプトが無効になっていてバイナリが見つからない場合は、npx --ignore-scripts=false inngest-cli@latest dev を実行して再試行してください。Bun はデフォルトでライフサイクルスクリプトをサポートしていないため、Bun プロジェクトでも CLI には npx を使用することをおすすめします。

inngest dev — ローカル Dev Server

Inngest のインメモリ版を起動します。ブラウザー UI は http://localhost:8288 で利用できます。

# Auto-discover apps on common ports/endpoints
npx inngest-cli@latest dev

# Specify your app URL
npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Custom port
npx inngest-cli@latest dev -p 9999

# Multiple apps
npx inngest-cli@latest dev \
  -u http://localhost:3000/api/inngest \
  -u http://localhost:4000/api/inngest

# Disable auto-discovery (use with -u)
npx inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest

CLI フラグ

フラグ	短縮形	デフォルト	説明
--sdk-url	-u	http://localhost:3000/api/inngest	アプリのサーブエンドポイント URL
--port	-p	8288	Dev Server のポート
--host			Dev Server のホスト
--no-discovery		false	アプリの自動検出を無効にします
--no-poll		false	アプリの変更をポーリングする機能を無効にします
--config			設定ファイルのパス
--connect-gateway-port		8289	Connect ゲートウェイエンドポイントのポート
--persist		false	再起動後もデータを保持します
--poll-interval		5	アプリのポーリング確認間隔（秒）
--queue-workers		100	エグゼキューターワーカーの数
--retry-interval		0	線形リトライ間隔（秒）
--tick		150	エグゼキューターキューのポーリング間隔（ミリ秒）

自動検出

--no-discovery を指定しない場合、Dev Server は一般的なポートとエンドポイントを自動的にスキャンします。

スキャン対象のポート： 3000、3030 など、一般的な開発用ポート

スキャン対象のエンドポイント：

• /api/inngest
• /x/inngest
• /.netlify/functions/inngest
• /.redwood/functions/inngest

設定ファイル

プロジェクトのルートに inngest.json（または .yaml、.toml）を作成します。CLI はディレクトリを上にたどってファイルを検索します。

{
  "sdk-url": [
    "http://localhost:3000/api/inngest",
    "http://localhost:3030/api/inngest"
  ],
  "no-discovery": true
}

# inngest.yaml
sdk-url:
  - "http://localhost:3000/api/inngest"
  - "http://localhost:3030/api/inngest"
no-discovery: true

環境変数

変数	説明
INNGEST_DEV	=1 は Dev モードを有効にします（署名検証を無効化）。=0 は Cloud モードを強制します。URL（例：http://localhost:8288）も指定できます。未設定の場合、デフォルトで Cloud モードになります。
INNGEST_BASE_URL	SDK と Inngest 間の通信に使用するホスト（例：http://localhost:8288）。ほとんどの場合、設定する必要はありません。
INNGEST_EVENT_KEY	イベント送信に使用する認証キー。ローカルでは任意のダミー値を使用できます。Dev Server は検証しません。
INNGEST_SIGNING_KEY	Inngest とアプリ間のリクエストを保護します。本番環境では必須です。 同期先となる Inngest 環境を決定します。
INNGEST_SIGNING_KEY_FALLBACK	署名キーのローテーションに使用するフォールバックキー（v3.18.0 以降）。
INNGEST_SERVE_ORIGIN	Inngest がアプリに接続するためのオリジン URL 全体（例：https://my-app.com）。リクエストヘッダーから自動推定されます。AWS Lambda、プロキシ、トンネルを使用する場合は明示的に設定してください。
INNGEST_SERVE_PATH	サーブエンドポイントの URL パス（例：/api/inngest）。ほとんどの場合、自動推定されます。
INNGEST_STREAMING	レスポンスストリーミング（true／false）を有効にします。Vercel とエッジランタイムでタイムアウト制限を延長します。
INNGEST_ENV	対象となる Inngest 環境。一部のプラットフォームでは自動検出されます。

サーブエンドポイントのデバッグ

serve() エンドポイントが正しく設定されていることを確認します。

curl -s http://localhost:3000/api/inngest | jq

{
  "message": "Inngest endpoint configured correctly.",
  "hasEventKey": false,
  "hasSigningKey": false,
  "functionsFound": 3
}

functionsFound が 0 の場合は、関数が serve() の呼び出しに渡されていることを確認してください。

関数のローカルテスト

SDK 経由でイベントを送信する

import { Inngest } from "inngest";

const inngest = new Inngest({ id: "my-app" });

await inngest.send({
  name: "user/signup.completed",
  data: {
    userId: "user_123",
    email: "[email protected]",
  },
});

curl 経由でイベントを送信する

curl -X POST "http://localhost:8288/e/test" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user/signup.completed",
    "data": {
      "userId": "user_123",
      "email": "[email protected]"
    }
  }'

URL パス内のイベントキー（上の例では test）には、ローカルで任意の値を指定できます。

@inngest/test による単体テスト

inngest@>=4.0.0 が必要です。

npm install -D @inngest/test

import { InngestTestEngine } from "@inngest/test";
import { helloWorld } from "./functions";

// Execute full function
const t = new InngestTestEngine({ function: helloWorld });
const { result } = await t.execute();
expect(result).toEqual("Hello World!");

// Test a single step
const { result: stepResult } = await t.executeStep("calculate-price");
expect(stepResult).toEqual(123);

// Assert step state
const { state } = await t.execute();
await expect(state["my-step"]).resolves.toEqual("output");
await expect(state["risky-step"]).rejects.toThrowError("failed");

// Mock events
const { result: eventResult } = await t.execute({
  events: [{ name: "demo/event.sent", data: { message: "Hi!" } }],
});

// Mock step responses
const { result: mockResult } = await t.execute({
  steps: [{ id: "external-api-call", handler() { return { status: "ok" }; } }],
});

// Mock sleep/waitForEvent (pause-inducing steps require mocking)
await t.execute({
  steps: [{ id: "wait-one-day", handler() {} }],
});

外部依存関係をモックするには、テストフレームワーク標準のモック機能（jest.mock、vi.mock など）を使用してください — @inngest/test は Inngest 固有のモックのみを処理します。

Docker セットアップ

スタンドアロン

docker run -p 8288:8288 -p 8289:8289 \
  inngest/inngest \
  inngest dev -u http://host.docker.internal:3000/api/inngest

ホストマシン上で実行されているアプリに到達するには host.docker.internal を使用します（Docker Desktop ではそのまま動作します）。Linux では、--add-host=host.docker.internal:host-gateway を追加するか、同等のホストアクセス方法を使用してください。

Docker Compose

services:
  app:
    build: ./app
    environment:
      - INNGEST_DEV=1
      - INNGEST_BASE_URL=http://inngest:8288
    ports:
      - "3000:3000"
  inngest:
    image: inngest/inngest
    command: "inngest dev -u http://app:3000/api/inngest"
    ports:
      - "8288:8288"
      - "8289:8289"

ポート 8288 はメインサーバーと UI です。ポート 8289 は connect() WebSocket ゲートウェイです。

重要: アプリで INNGEST_DEV=1 を設定してください — TypeScript SDK はデフォルトで Cloud モードになり、Dev Server をスキップします。

MCP サーバー（AI 開発ツール）

プラグインは、デプロイ済みリソースへの OAuth アクセス用に inngest-cloud をバンドルしています。 ローカル Dev Server MCP は、inngest-dev という名前の別のオプトイン接続です。 どちらも同じコーディングセッションで使用できます。ローカル MCP のセットアップや接続の トラブルシューティングについては、ローカル MCP セットアップをお読みください。

Dev Server 上のアプリと実行には、構成済みのローカル接続を使用してください （デフォルトでは inngest-dev。既存の接続がある場合はその名前を維持してください）。デプロイ済みリソースには inngest-cloud を使用し、目的のアカウントと環境を選択してください。対象が不明確な場合は、 どちらのサーバーを呼び出す前に解決してください。ローカルサーバーがオフラインであることを理由に、 ローカルから Cloud に切り替えないでください。

各サーバーのライブツールスキーマを確認してください。ローカルツールには、アプリ、関数、イベント、 実行、トレースの操作に加え、埋め込みドキュメント検索が含まれます。利用可否 と入力は、実行中の Dev Server のバージョンによって異なります。

inngest start — セルフホスト本番環境

Inngest をセルフホストの本番サーバーとして実行します。inngest dev とは異なります — これは本番ワークロード向けです。

inngest start --event-key <key> --signing-key <key>

フラグ	短縮形	デフォルト	説明
--port	-p	8288	サーバーポート
--signing-key			リクエスト署名用の 16 進キー（偶数文字数）
--event-key			アプリ用の認証キー（繰り返し指定可能）
--sdk-url	-u		アプリの serve URL（繰り返し指定可能）
--redis-uri			外部 Redis 接続
--postgres-uri			外部 PostgreSQL 接続
--sqlite-dir			SQLite データベースディレクトリ
--poll-interval		0	アプリ同期のポーリング間隔（秒）
--queue-workers		100	エグゼキューターのワーカー数
--connect-gateway-port		8289	Connect ゲートウェイのポート
--retry-interval		0	線形リトライ間隔（秒）
--tick		150	エグゼキューターキューのポーリング間隔（ミリ秒）
--no-ui			Web UI と GraphQL API を無効化
--postgres-conn-max-idle-time		5	PostgreSQL アイドル接続の存続時間（分）
--postgres-conn-max-lifetime		30	PostgreSQL 接続の最大再利用時間（分）
--postgres-max-idle-conns		10	PostgreSQL の最大アイドル接続数
--postgres-max-open-conns		100	PostgreSQL の最大オープン接続数

--log-level、--verbose、--json などのグローバルフラグも使用できます。環境変数については、現在の CLI とデプロイのドキュメントに従ってください。すべてのフラグに INNGEST_ 環境変数の同等のものがあると想定しないでください。

デフォルトの永続化: インメモリ Redis + ./.inngest/main.db の SQLite。本番環境では、外部 Redis と PostgreSQL を使用してください。

デプロイワークフロー

ローカル開発 → 本番

1. inngest dev でローカル開発 — キーは不要、本番向けのコード変更も不要
2. ホスティングプラットフォームにアプリをデプロイ
3. 次の 3 つの方法のいずれかで Inngest と同期:

# Option 1: Curl from CI/CD
curl -X PUT https://your-app.com/api/inngest --fail-with-body

# Option 2: Vercel/Netlify integrations (automatic on deploy)

# Option 3: Manual sync via Inngest Cloud dashboard

4. 本番環境で環境変数を設定:

INNGEST_EVENT_KEY=<your-event-key>
INNGEST_SIGNING_KEY=<your-signing-key>

ローカル開発から本番環境への移行時にコード変更は不要です。SDK が環境を自動的に検出します。

プラットフォーム固有の注意点

プラットフォーム	注意点
Express	express.json() ミドルウェアが必要です。デフォルトのボディ上限は 100kb なので、Inngest のペイロード（最大 4MB）を処理できるよう増やしてください
AWS Lambda	INNGEST_SERVE_ORIGIN と INNGEST_SERVE_PATH を明示的に設定してください。自動推論は失敗します
Firebase Cloud Functions	INNGEST_SERVE_PATH 環境変数を設定する必要があります
DigitalOcean Functions	serve() の設定で serveOrigin と servePath の両方が必要です
Cloudflare Workers（Wrangler --remote）	Dev Server への接続にはトンネル（ngrok/localtunnel）が必要です
Supabase Edge Functions	servePath は関数名と一致させる必要があります。Supabase がリクエストパスを書き換えます
Google Cloud Run（第1世代）	公式にはサポートされていません。署名検証エラーが発生する可能性があります
Docker	INNGEST_DEV=1 を設定する必要があります。SDK はデフォルトで Cloud モードになります
外部 Webhook（Stripe、Clerk）	ローカルテストにはトンネルソリューション（ngrok、localtunnel）が必要です

クイックリファレンス

# Start dev server with auto-discovery
npx inngest-cli@latest dev

# Start with explicit app URL
npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Check serve endpoint health
curl -s http://localhost:3000/api/inngest | jq

# Send test event via curl
curl -X POST http://localhost:8288/e/test -d '{"name": "test/event", "data": {}}'

# Sync after deploy (CI/CD)
curl -X PUT https://your-app.com/api/inngest --fail-with-body

# Self-hosted production
inngest start --event-key <key> --signing-key <key>

トラブルシューティング

問題	原因	解決策
Dev Server が関数を見つけられない	アプリが起動していない、またはポートが間違っている	まずアプリを起動してください。-u を使って正しい URL を指定します
デバッグ出力に functionsFound: 0 と表示される	関数が serve() に渡されていない	すべての関数が serve() に渡す配列に含まれているか確認してください
SDK が Dev Server ではなく Cloud に接続する	INNGEST_DEV が設定されていない	環境で INNGEST_DEV=1 を設定してください
関数が誤った Inngest 環境に同期される	署名キーが間違っている	INNGEST_SIGNING_KEY が対象環境と一致しているか確認してください
Inngest ダッシュボードにアプリが重複して表示される	アプリの id が変更された	new Inngest({ id }) の id をデプロイ間で固定してください
Webhook イベントが Dev Server に届かない	トンネルが構成されていない	外部 Webhook ソースには ngrok または localtunnel を使用してください
ダッシュボードに「Unattached sync」と表示される	自動同期がサイレントに失敗した	統合ログを確認し、手動で再同期してください

SDK のインストールについては inngest-setup を、関数の構成については inngest-durable-functions を参照してください。