Update to Inngest

{
  "description": "Use when installing or running the Inngest CLI and Dev Server for local development, local testing, serve endpoint debugging, Docker or Docker Compose setup, MCP configuration, self-hosted `inngest start`, or deployment workflow checks. Covers `inngest dev`, `inngest start`, auto-discovery, config files, environment variables, `@inngest/test`, local event sending, platform gotchas, and production/self-hosted server flags.",
  "included_files": [
    {
      "relative_path": "references/local-mcp.md",
      "size_in_bytes": 3644
    }
  ],
  "name": "inngest-cli",
  "skill_md_contents": "---\nname: inngest-cli\ndescription: Use when installing or running the Inngest CLI and Dev Server for local development, local testing, serve endpoint debugging, Docker or Docker Compose setup, MCP configuration, self-hosted `inngest start`, or deployment workflow checks. Covers `inngest dev`, `inngest start`, auto-discovery, config files, environment variables, `@inngest/test`, local event sending, platform gotchas, and production/self-hosted server flags.\n---\n\n# Inngest CLI\n\nMaster the Inngest CLI for local development, testing, and self-hosted production. The CLI provides the Dev Server — a fully-featured, open-source local version of the Inngest Platform.\n\n> **These skills are focused on TypeScript.** For Python or Go, refer to the [Inngest documentation](https://www.inngest.com/llms.txt) for language-specific guidance. Core concepts apply across all languages.\n\nUse this skill for CLI setup, Dev Server workflows, local testing, Docker, MCP, and self-hosted server operations. For run/trace inspection through `inngest api`, use `inngest-api-cli` when available.\n\n## Installation\n\n```bash\n# npx (recommended — always latest)\nnpx inngest-cli@latest dev\n\n# yarn\nyarn dlx inngest-cli@latest dev\n\n# pnpm\npnpm dlx inngest-cli@latest dev\n\n# Global install\nnpm install -g inngest-cli\n\n# Docker\ndocker pull inngest/inngest\n```\n\nIf your npm configuration disables lifecycle scripts and the binary is missing, retry with `npx --ignore-scripts=false inngest-cli@latest dev`. Bun does not support lifecycle scripts by default, so prefer `npx` for the CLI even in Bun projects.\n\n## `inngest dev` — Local Dev Server\n\nStarts an in-memory local version of Inngest with a browser UI at `http://localhost:8288`.\n\n```bash\n# Auto-discover apps on common ports/endpoints\nnpx inngest-cli@latest dev\n\n# Specify your app URL\nnpx inngest-cli@latest dev -u http://localhost:3000/api/inngest\n\n# Custom port\nnpx inngest-cli@latest dev -p 9999\n\n# Multiple apps\nnpx inngest-cli@latest dev \\\n  -u http://localhost:3000/api/inngest \\\n  -u http://localhost:4000/api/inngest\n\n# Disable auto-discovery (use with -u)\nnpx inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest\n```\n\n### CLI Flags\n\n| Flag | Short | Default | Description |\n|---|---|---|---|\n| `--sdk-url` | `-u` | `http://localhost:3000/api/inngest` | App serve endpoint URL(s) |\n| `--port` | `-p` | `8288` | Dev Server port |\n| `--host` | | | Dev Server host |\n| `--no-discovery` | | `false` | Disable auto-discovery of apps |\n| `--no-poll` | | `false` | Disable polling apps for changes |\n| `--config` | | | Path to configuration file |\n| `--connect-gateway-port` | | `8289` | Connect gateway endpoint port |\n| `--persist` | | `false` | Persist data between restarts |\n| `--poll-interval` | | `5` | Seconds between app polling checks |\n| `--queue-workers` | | `100` | Number of executor workers |\n| `--retry-interval` | | `0` | Linear retry interval in seconds |\n| `--tick` | | `150` | Executor queue polling interval in milliseconds |\n\n### Auto-Discovery\n\nWithout `--no-discovery`, the Dev Server scans common ports and endpoints automatically:\n\n**Ports scanned:** Common development ports including 3000, 3030, and others\n\n**Endpoints scanned:**\n- `/api/inngest`\n- `/x/inngest`\n- `/.netlify/functions/inngest`\n- `/.redwood/functions/inngest`\n\n## Configuration File\n\nCreate an `inngest.json` (or `.yaml`, `.toml`) in your project root. The CLI walks up directories to find it.\n\n```json\n{\n  \"sdk-url\": [\n    \"http://localhost:3000/api/inngest\",\n    \"http://localhost:3030/api/inngest\"\n  ],\n  \"no-discovery\": true\n}\n```\n\n```yaml\n# inngest.yaml\nsdk-url:\n  - \"http://localhost:3000/api/inngest\"\n  - \"http://localhost:3030/api/inngest\"\nno-discovery: true\n```\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `INNGEST_DEV` | `=1` enables Dev Mode (disables signature verification). `=0` forces Cloud mode. Accepts a URL (e.g., `http://localhost:8288`). **Defaults to Cloud mode if unset.** |\n| `INNGEST_BASE_URL` | Host for SDK-to-Inngest communication (e.g., `http://localhost:8288`). Leave unset in most cases. |\n| `INNGEST_EVENT_KEY` | Authentication key for sending events. **Use any dummy value locally** — Dev Server does not validate. |\n| `INNGEST_SIGNING_KEY` | Secures requests between Inngest and your app. **Required in production.** Determines which Inngest environment receives syncs. |\n| `INNGEST_SIGNING_KEY_FALLBACK` | Fallback key for signing key rotation (v3.18.0+). |\n| `INNGEST_SERVE_ORIGIN` | Full origin URL for Inngest to reach your app (e.g., `https://my-app.com`). Auto-inferred from request headers; **set explicitly for AWS Lambda, proxies, or tunnels.** |\n| `INNGEST_SERVE_PATH` | URL path to your serve endpoint (e.g., `/api/inngest`). Auto-inferred in most cases. |\n| `INNGEST_STREAMING` | Enable response streaming (`true`/`false`). Extends timeout limits on Vercel and edge runtimes. |\n| `INNGEST_ENV` | Target Inngest Environment. Auto-detected on some platforms. |\n\n## Debugging Your Serve Endpoint\n\nVerify your `serve()` endpoint is configured correctly:\n\n```bash\ncurl -s http://localhost:3000/api/inngest | jq\n```\n\n```json\n{\n  \"message\": \"Inngest endpoint configured correctly.\",\n  \"hasEventKey\": false,\n  \"hasSigningKey\": false,\n  \"functionsFound\": 3\n}\n```\n\nIf `functionsFound` is `0`, check that your functions are passed to the `serve()` call.\n\n## Testing Functions Locally\n\n### Send Events via SDK\n\n```typescript\nimport { Inngest } from \"inngest\";\n\nconst inngest = new Inngest({ id: \"my-app\" });\n\nawait inngest.send({\n  name: \"user/signup.completed\",\n  data: {\n    userId: \"user_123\",\n    email: \"user@example.com\",\n  },\n});\n```\n\n### Send Events via curl\n\n```bash\ncurl -X POST \"http://localhost:8288/e/test\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"user/signup.completed\",\n    \"data\": {\n      \"userId\": \"user_123\",\n      \"email\": \"user@example.com\"\n    }\n  }'\n```\n\nThe event key in the URL path (`test` above) can be any value locally.\n\n### Unit Testing with `@inngest/test`\n\nRequires `inngest@>=4.0.0`.\n\n```bash\nnpm install -D @inngest/test\n```\n\n```typescript\nimport { InngestTestEngine } from \"@inngest/test\";\nimport { helloWorld } from \"./functions\";\n\n// Execute full function\nconst t = new InngestTestEngine({ function: helloWorld });\nconst { result } = await t.execute();\nexpect(result).toEqual(\"Hello World!\");\n\n// Test a single step\nconst { result: stepResult } = await t.executeStep(\"calculate-price\");\nexpect(stepResult).toEqual(123);\n\n// Assert step state\nconst { state } = await t.execute();\nawait expect(state[\"my-step\"]).resolves.toEqual(\"output\");\nawait expect(state[\"risky-step\"]).rejects.toThrowError(\"failed\");\n\n// Mock events\nconst { result: eventResult } = await t.execute({\n  events: [{ name: \"demo/event.sent\", data: { message: \"Hi!\" } }],\n});\n\n// Mock step responses\nconst { result: mockResult } = await t.execute({\n  steps: [{ id: \"external-api-call\", handler() { return { status: \"ok\" }; } }],\n});\n\n// Mock sleep/waitForEvent (pause-inducing steps require mocking)\nawait t.execute({\n  steps: [{ id: \"wait-one-day\", handler() {} }],\n});\n```\n\n**Mock external dependencies** with your test framework's standard mocking (`jest.mock`, `vi.mock`, etc.) — `@inngest/test` handles only Inngest-specific mocking.\n\n## Docker Setup\n\n### Standalone\n\n```bash\ndocker run -p 8288:8288 -p 8289:8289 \\\n  inngest/inngest \\\n  inngest dev -u http://host.docker.internal:3000/api/inngest\n```\n\nUse `host.docker.internal` to reach your app running on the host machine (works out of the box on Docker Desktop). On Linux, add `--add-host=host.docker.internal:host-gateway` or use an equivalent host-access method.\n\n### Docker Compose\n\n```yaml\nservices:\n  app:\n    build: ./app\n    environment:\n      - INNGEST_DEV=1\n      - INNGEST_BASE_URL=http://inngest:8288\n    ports:\n      - \"3000:3000\"\n  inngest:\n    image: inngest/inngest\n    command: \"inngest dev -u http://app:3000/api/inngest\"\n    ports:\n      - \"8288:8288\"\n      - \"8289:8289\"\n```\n\n**Port 8288** is the main server and UI. **Port 8289** is the `connect()` WebSocket gateway.\n\n**Critical:** Set `INNGEST_DEV=1` on your app — the TypeScript SDK defaults to Cloud mode, which will skip the Dev Server.\n\n## MCP Server (AI Dev Tools)\n\nThe plugins bundle `inngest-cloud` for OAuth access to deployed resources.\nLocal Dev Server MCP is a separate, opt-in connection named `inngest-dev`.\nBoth can be used in the same coding session. For local MCP setup or connection\ntroubleshooting, read [Local MCP setup](references/local-mcp.md).\n\nUse the configured local connection for apps and runs on the Dev Server\n(`inngest-dev` by default; keep an existing connection’s name). Use\n`inngest-cloud` for deployed resources, selecting the intended account and\nenvironment. If the target is unclear, resolve it before calling either\nserver. Never switch from local to Cloud because the local server is offline.\n\nRead each server's live tool schemas. Local tools include app, function, event,\nrun, and trace operations, plus embedded documentation search. Availability\nand inputs depend on the running Dev Server version.\n\n## `inngest start` — Self-Hosted Production\n\nRuns Inngest as a self-hosted production server. **Not the same as `inngest dev`** — this is for production workloads.\n\n```bash\ninngest start --event-key <key> --signing-key <key>\n```\n\n| Flag | Short | Default | Description |\n|---|---|---|---|\n| `--port` | `-p` | `8288` | Server port |\n| `--signing-key` | | | Hex key for request signing (even character count) |\n| `--event-key` | | | Authentication key for apps (repeatable) |\n| `--sdk-url` | `-u` | | App serve URLs (repeatable) |\n| `--redis-uri` | | | External Redis connection |\n| `--postgres-uri` | | | External PostgreSQL connection |\n| `--sqlite-dir` | | | SQLite database directory |\n| `--poll-interval` | | `0` | App sync polling interval (seconds) |\n| `--queue-workers` | | `100` | Number of executor workers |\n| `--connect-gateway-port` | | `8289` | Connect gateway port |\n| `--retry-interval` | | `0` | Linear retry interval in seconds |\n| `--tick` | | `150` | Executor queue polling interval in milliseconds |\n| `--no-ui` | | | Disable web UI and GraphQL API |\n| `--postgres-conn-max-idle-time` | | `5` | PostgreSQL idle connection lifetime in minutes |\n| `--postgres-conn-max-lifetime` | | `30` | PostgreSQL maximum connection reuse time in minutes |\n| `--postgres-max-idle-conns` | | `10` | PostgreSQL max idle connections |\n| `--postgres-max-open-conns` | | `100` | PostgreSQL max open connections |\n\nGlobal flags such as `--log-level`, `--verbose`, and `--json` are also available. For environment variables, follow the current CLI and deployment docs; do not assume every flag has an `INNGEST_` environment variable equivalent.\n\nDefault persistence: in-memory Redis + SQLite at `./.inngest/main.db`. For production, use external Redis and PostgreSQL.\n\n## Deployment Workflow\n\n### Local Development → Production\n\n1. **Develop locally** with `inngest dev` — no keys needed, no code changes for production\n2. **Deploy your app** to your hosting platform\n3. **Sync with Inngest** using one of three methods:\n\n```bash\n# Option 1: Curl from CI/CD\ncurl -X PUT https://your-app.com/api/inngest --fail-with-body\n\n# Option 2: Vercel/Netlify integrations (automatic on deploy)\n\n# Option 3: Manual sync via Inngest Cloud dashboard\n```\n\n4. **Set environment variables** in production:\n\n```bash\nINNGEST_EVENT_KEY=<your-event-key>\nINNGEST_SIGNING_KEY=<your-signing-key>\n```\n\n**No code changes** are needed when moving from local dev to production. The SDK automatically detects the environment.\n\n## Platform-Specific Gotchas\n\n| Platform | Gotcha |\n|---|---|\n| **Express** | Requires `express.json()` middleware; default body limit is `100kb` — increase to handle Inngest payloads (up to 4MB) |\n| **AWS Lambda** | Set `INNGEST_SERVE_ORIGIN` and `INNGEST_SERVE_PATH` explicitly — auto-inference fails |\n| **Firebase Cloud Functions** | Must set `INNGEST_SERVE_PATH` env var |\n| **DigitalOcean Functions** | Both `serveOrigin` and `servePath` required in `serve()` config |\n| **Cloudflare Workers (Wrangler `--remote`)** | Requires tunnel (ngrok/localtunnel) for Dev Server connection |\n| **Supabase Edge Functions** | `servePath` must match function name — Supabase rewrites request paths |\n| **Google Cloud Run (1st gen)** | Not officially supported; may cause signature verification errors |\n| **Docker** | Must set `INNGEST_DEV=1` — SDK defaults to Cloud mode |\n| **External webhooks (Stripe, Clerk)** | Require tunnel solution (ngrok, localtunnel) for local testing |\n\n## Quick Reference\n\n```bash\n# Start dev server with auto-discovery\nnpx inngest-cli@latest dev\n\n# Start with explicit app URL\nnpx inngest-cli@latest dev -u http://localhost:3000/api/inngest\n\n# Check serve endpoint health\ncurl -s http://localhost:3000/api/inngest | jq\n\n# Send test event via curl\ncurl -X POST http://localhost:8288/e/test -d '{\"name\": \"test/event\", \"data\": {}}'\n\n# Sync after deploy (CI/CD)\ncurl -X PUT https://your-app.com/api/inngest --fail-with-body\n\n# Self-hosted production\ninngest start --event-key <key> --signing-key <key>\n```\n\n## Troubleshooting\n\n| Issue | Cause | Solution |\n|---|---|---|\n| Dev Server doesn't find functions | App not running or wrong port | Start your app first; use `-u` to specify the correct URL |\n| `functionsFound: 0` in debug output | Functions not passed to `serve()` | Verify all functions are in the array passed to `serve()` |\n| SDK connects to Cloud instead of Dev Server | `INNGEST_DEV` not set | Set `INNGEST_DEV=1` in your environment |\n| Functions sync to wrong Inngest environment | Wrong signing key | Check `INNGEST_SIGNING_KEY` matches target environment |\n| Duplicate app in Inngest dashboard | App `id` was changed | Keep the `id` in `new Inngest({ id })` stable across deploys |\n| Webhook events not reaching Dev Server | No tunnel configured | Use ngrok or localtunnel for external webhook sources |\n| \"Unattached sync\" in dashboard | Auto-sync failed silently | Check integration logs; resync manually |\n\nSee [inngest-setup](../inngest-setup/SKILL.md) for SDK installation and [inngest-durable-functions](../inngest-durable-functions/SKILL.md) for function configuration.\n"
}