inngest-cli

Q: How do I install inngest-cli?

Run npx skills add https://github.com/inngest/inngest-skills --skill inngest-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/inngest-cli/ (personal) or .claude/skills/inngest-cli/ (project).

by inngestDevOps & Cloud

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.

Installs: 820
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/inngest/inngest-skills --skill inngest-cli

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads inngest-cli automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Flag	Short	Default	Description
`--sdk-url`	`-u`	`http://localhost:3000/api/inngest`	App serve endpoint URL(s)
`--port`	`-p`	`8288`	Dev Server port
`--host`			Dev Server host
`--no-discovery`		`false`	Disable auto-discovery of apps
`--no-poll`		`false`	Disable polling apps for changes
`--config`			Path to configuration file
`--connect-gateway-port`		`8289`	Connect gateway endpoint port
`--persist`		`false`	Persist data between restarts
`--poll-interval`		`5`	Seconds between app polling checks
`--queue-workers`		`100`	Number of executor workers
`--retry-interval`		`0`	Linear retry interval in seconds
`--tick`		`150`	Executor queue polling interval in milliseconds

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

Variable	Description
`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.
`INNGEST_BASE_URL`	Host for SDK-to-Inngest communication (e.g., `http://localhost:8288`). Leave unset in most cases.
`INNGEST_EVENT_KEY`	Authentication key for sending events. Use any dummy value locally — Dev Server does not validate.
`INNGEST_SIGNING_KEY`	Secures requests between Inngest and your app. Required in production. Determines which Inngest environment receives syncs.
`INNGEST_SIGNING_KEY_FALLBACK`	Fallback key for signing key rotation (v3.18.0+).
`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.
`INNGEST_SERVE_PATH`	URL path to your serve endpoint (e.g., `/api/inngest`). Auto-inferred in most cases.
`INNGEST_STREAMING`	Enable response streaming (`true`/`false`). Extends timeout limits on Vercel and edge runtimes.
`INNGEST_ENV`	Target Inngest Environment. Auto-detected on some platforms.

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: "user@example.com",
  },
});

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": "user@example.com"
    }
  }'

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>

Flag	Short	Default	Description
`--port`	`-p`	`8288`	Server port
`--signing-key`			Hex key for request signing (even character count)
`--event-key`			Authentication key for apps (repeatable)
`--sdk-url`	`-u`		App serve URLs (repeatable)
`--redis-uri`			External Redis connection
`--postgres-uri`			External PostgreSQL connection
`--sqlite-dir`			SQLite database directory
`--poll-interval`		`0`	App sync polling interval (seconds)
`--queue-workers`		`100`	Number of executor workers
`--connect-gateway-port`		`8289`	Connect gateway port
`--retry-interval`		`0`	Linear retry interval in seconds
`--tick`		`150`	Executor queue polling interval in milliseconds
`--no-ui`			Disable web UI and GraphQL API
`--postgres-conn-max-idle-time`		`5`	PostgreSQL idle connection lifetime in minutes
`--postgres-conn-max-lifetime`		`30`	PostgreSQL maximum connection reuse time in minutes
`--postgres-max-idle-conns`		`10`	PostgreSQL max idle connections
`--postgres-max-open-conns`		`100`	PostgreSQL max open connections

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

Develop locally with inngest dev — no keys needed, no code changes for production
Deploy your app to your hosting platform
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

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

Platform	Gotcha
Express	Requires `express.json()` middleware; default body limit is `100kb` — increase to handle Inngest payloads (up to 4MB)
AWS Lambda	Set `INNGEST_SERVE_ORIGIN` and `INNGEST_SERVE_PATH` explicitly — auto-inference fails
Firebase Cloud Functions	Must set `INNGEST_SERVE_PATH` env var
DigitalOcean Functions	Both `serveOrigin` and `servePath` required in `serve()` config
Cloudflare Workers (Wrangler `--remote`)	Requires tunnel (ngrok/localtunnel) for Dev Server connection
Supabase Edge Functions	`servePath` must match function name — Supabase rewrites request paths
Google Cloud Run (1st gen)	Not officially supported; may cause signature verification errors
Docker	Must set `INNGEST_DEV=1` — SDK defaults to Cloud mode
External webhooks (Stripe, Clerk)	Require tunnel solution (ngrok, localtunnel) for local testing

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

Issue	Cause	Solution
Dev Server doesn't find functions	App not running or wrong port	Start your app first; use `-u` to specify the correct URL
`functionsFound: 0` in debug output	Functions not passed to `serve()`	Verify all functions are in the array passed to `serve()`
SDK connects to Cloud instead of Dev Server	`INNGEST_DEV` not set	Set `INNGEST_DEV=1` in your environment
Functions sync to wrong Inngest environment	Wrong signing key	Check `INNGEST_SIGNING_KEY` matches target environment
Duplicate app in Inngest dashboard	App `id` was changed	Keep the `id` in `new Inngest({ id })` stable across deploys
Webhook events not reaching Dev Server	No tunnel configured	Use ngrok or localtunnel for external webhook sources
"Unattached sync" in dashboard	Auto-sync failed silently	Check integration logs; resync manually

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

FAQ

What does the inngest-cli skill do?

How do I install inngest-cli?

Run npx skills add https://github.com/inngest/inngest-skills --skill inngest-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/inngest-cli/ (personal) or .claude/skills/inngest-cli/ (project).

Which AI agents can use inngest-cli?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is inngest-cli safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains inngest-cli?

It is published by inngest in inngest/inngest-skills. It has 820 recorded installs.

More from inngest/inngest-skills

View all →

inngest-durable-functions

inngest/inngest-skills

Use when building functions that must survive process crashes, retry automatically on failure, run on a schedule, react to events, or maintain state across infrastructure failures — e.g., webhook handlers that drop events, flaky cron jobs, background jobs that fail mid-execution, or workflows that need to resume where they left off. Covers Inngest function configuration, triggers (events, cron, invoke), step execution and memoization, idempotency, cancellation, error handling, retries, logging, and observability.

DevOps & Cloud3.9K installs

inngest-events

inngest/inngest-skills

Use when designing event-driven workflows, decoupling services, implementing fan-out patterns (one trigger, many downstream handlers), implementing idempotent event handling with IDs (24-hour dedupe window), or handling at-least-once delivery from external sources like Stripe webhooks. Covers Inngest event schema, payload format, naming conventions, IDs for idempotency, the ts param, fan-out patterns, and system events like inngest/function.failed.

Backend & APIs3.8K installs

inngest-steps

inngest/inngest-skills

Use when implementing delays that must survive process restarts (e.g., 24-hour cart abandonment, scheduled follow-ups), waiting for human approval or external events with timeouts (review gates, webhook callbacks, async API completion), polling external services without losing state on crashes, calling other functions and awaiting their results, memoizing expensive operations so they don't re-run on retry, or running async work in parallel inside a workflow. Covers Inngest step methods: step.run, step.sleep, step.waitForEvent, step.waitForSignal, step.sendEvent, step.invoke, step.ai, plus patterns for loops and parallel execution.

Backend & APIs3.8K installs

inngest-setup

inngest/inngest-skills

Use when adding durable execution to a TypeScript project — building retry-safe webhook handlers, background jobs that survive crashes, scheduled tasks, or long-running workflows that outlive a single request. Covers Inngest SDK installation, client config, environment variables, serve endpoints (Next.js, Express, Hono, Fastify), connect-as-worker mode, and the local dev server.

Backend & APIs3.8K installs

inngest-middleware

inngest/inngest-skills

Use when adding cross-cutting concerns to durable functions — structured logging or tracing across all functions, error tracking with Sentry, payload encryption for sensitive data, dependency injection of clients (DB, Stripe, etc.) into function handlers, custom telemetry, or behavior that should apply uniformly across many functions. Covers Inngest middleware lifecycle, creating custom middleware, dependencyInjectionMiddleware, @inngest/middleware-encryption, @inngest/middleware-sentry, and custom middleware patterns.

DevOps & Cloud3.6K installs

inngest-flow-control

inngest/inngest-skills

Use when handling external API rate limits (e.g., OpenAI 429s, HubSpot or Stripe rate limits), preventing duplicate work from rapid event bursts (debouncing user actions), spreading load over time, ensuring per-tenant fairness, processing events in batches, limiting concurrent runs of the same operation, or assigning priority to important runs. Covers Inngest flow control: concurrency limits with keys, throttling, rate limiting, debounce, priority, singleton, and event batching.

Backend & APIs1.6K installs

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

inngest-cli

Install

Install

Describe the task

Review the result

SKILL.md

Inngest CLI

Installation

inngest dev — Local Dev Server

CLI Flags

Auto-Discovery

Configuration File

Environment Variables

Debugging Your Serve Endpoint

Testing Functions Locally

Send Events via SDK

Send Events via curl

Unit Testing with @inngest/test

Docker Setup

Standalone

Docker Compose

MCP Server (AI Dev Tools)

inngest start — Self-Hosted Production

Deployment Workflow

Local Development → Production

Platform-Specific Gotchas

Quick Reference

Troubleshooting

FAQ

More from inngest/inngest-skills

Popular devops & cloud skills

`inngest dev` — Local Dev Server

Unit Testing with `@inngest/test`

`inngest start` — Self-Hosted Production