Inngest CLI

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

These skills are focused on TypeScript. For Python or Go, refer to the Inngest documentation for language-specific guidance. Core concepts apply across all languages.

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

Installation

# 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

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

inngest dev — Local Dev Server

Starts an in-memory local version of Inngest with a browser UI at 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 Flags

Auto-Discovery

Without --no-discovery, the Dev Server scans common ports and endpoints automatically:

Ports scanned: Common development ports including 3000, 3030, and others

Endpoints scanned:

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

Configuration File

Create an inngest.json (or .yaml, .toml) in your project root. The CLI walks up directories to find it.

{
  "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

Environment Variables

Debugging Your Serve Endpoint

Verify your serve() endpoint is configured correctly:

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

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

If functionsFound is 0, check that your functions are passed to the serve() call.

Testing Functions Locally

Send Events via 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]",
  },
});

Send Events via 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]"
    }
  }'

The event key in the URL path (test above) can be any value locally.

Unit Testing with @inngest/test

Requires 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() {} }],
});

Mock external dependencies with your test framework's standard mocking (jest.mock, vi.mock, etc.) — @inngest/test handles only Inngest-specific mocking.

Docker Setup

Standalone

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

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

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"

Port 8288 is the main server and UI. Port 8289 is the connect() WebSocket gateway.

Critical: Set INNGEST_DEV=1 on your app — the TypeScript SDK defaults to Cloud mode, which will skip the Dev Server.

MCP Server (AI Dev Tools)

The plugins bundle inngest-cloud for OAuth access to deployed resources. Local Dev Server MCP is a separate, opt-in connection named inngest-dev. Both can be used in the same coding session. For local MCP setup or connection troubleshooting, read Local MCP setup.

Use the configured local connection for apps and runs on the Dev Server (inngest-dev by default; keep an existing connection’s name). Use inngest-cloud for deployed resources, selecting the intended account and environment. If the target is unclear, resolve it before calling either server. Never switch from local to Cloud because the local server is offline.

Read each server's live tool schemas. Local tools include app, function, event, run, and trace operations, plus embedded documentation search. Availability and inputs depend on the running Dev Server version.

inngest start — Self-Hosted Production

Runs Inngest as a self-hosted production server. Not the same as `inngest dev` — this is for production workloads.

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

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

Default persistence: in-memory Redis + SQLite at ./.inngest/main.db. For production, use external Redis and PostgreSQL.

Deployment Workflow

Local Development → Production

1. Develop locally with inngest dev — no keys needed, no code changes for production
2. Deploy your app to your hosting platform
3. Sync with Inngest using one of three methods:

# 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

1. Set environment variables in production:

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

No code changes are needed when moving from local dev to production. The SDK automatically detects the environment.

Platform-Specific Gotchas

Quick Reference

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

Troubleshooting

See inngest-setup for SDK installation and inngest-durable-functions for function configuration.