Inngest API CLI

Use this skill when the task is operational: inspect, debug, sync, invoke, or query Inngest API resources through the terminal. This skill is intentionally prescriptive so agents can act without guessing.

For general CLI setup,

inngest dev

, Docker, local testing, MCP setup, or self-hosted

inngest start

, use

inngest-cli

. For code changes, pair this with the domain skill that owns the code pattern:

inngest-setup

inngest-durable-functions

inngest-events

inngest-steps

inngest-flow-control

inngest-realtime

, or

inngest-middleware

First Move

Verify the current CLI surface before relying on memory:

bash

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

The active API command is

inngest api

. If prompt context or old docs mention

inngest alpha api

, switch to

inngest api

Use

inngest-api

only when:

The CLI does not expose the needed endpoint.
The user explicitly asks for raw REST API v2.
You need the OpenAPI spec or LLM API docs to resolve request shape.

For complete command flags, read references/cli-commands.md after this skill triggers.

Target Rules

Local is the default target for
```
inngest api
```
.
Cloud Production requires
```
--prod
```
.
Non-production Cloud environments require
```
INNGEST_ENV=<name>
```
or
```
--env
```
.
Prefer
```
INNGEST_API_KEY
```
for Cloud API access.
Do not pass API keys inline with
```
--api-key <secret>
```
unless the user explicitly accepts process-list and transcript exposure.
Never write API keys, event keys, signing keys, webhook URLs, or decrypted secrets into source files, docs, fixtures, or final answers.

Common targets:

bash

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

Local Development

For local app work:

Start the user's app with local dev mode when applicable, for example
```
INNGEST_DEV=1 npm run dev
```
.
Start the dev server:
bash
```
npx inngest-cli@latest dev
```
Prefer Dev Server MCP tools, when available, to list local functions, send test events, inspect runs, and watch status.
Use
```
npx inngest-cli@latest api ...
```
for API-compatible local checks, command-help verification, and workflows not exposed through MCP.

If the local API says the dev server is unavailable, start

inngest dev

or switch to Cloud with

--prod

when the user is debugging deployed runs.

Command Routing

Use this table before asking the human for more context.

Situation	Command path
Check CLI/API reachability	`api health`
Confirm Cloud auth	`api --prod get-account`
List environments	`api --prod get-account-envs --limit 10`
List event keys	`api --prod get-account-event-keys --limit 10`
List signing keys	`api --prod get-account-signing-keys --limit 10`
List webhooks	`api --prod get-webhooks`
User gives a run ID	`api --prod get-function-run <run_id>`
Need step-level detail	`api --prod get-function-trace <run_id> --include-output`
User gives an event ID	`api --prod get-event-runs <event_id> --limit 5 --include-output`
Sync a known app ID	`api --prod sync-app --app-id <app_id> --url <serve_url>`
Invoke a known app/function ID	`api --prod invoke-function --app-id <app_id> --function-id <function_id> --data '<json>'`
Discover Insights tables	`api --prod get-insights-tables`
Discover event schemas for Insights	`api --prod get-insights-event-schemas --limit 25`
Draft an Insights query	`api --prod query-insights-prompt --prompt '<request>'`
Run an Insights query	`api --prod query-insights --query '<sql>'`

If a command accepts positional IDs, prefer positional IDs in examples because they are shorter and match current help. Flag forms such as

--run-id

are also accepted by the current CLI for many path parameters.

Debug a Run

When the user gives a run ID:

bash

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

Summarize status, failed spans, retry state, timing, error names/messages, and the likely code boundary to inspect. Do not paste full traces unless asked.

When the user gives an event ID:

bash

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

Pick the relevant run from the response, then fetch the run and trace. If multiple runs are plausible, explain the candidates and use timestamps, function IDs, or failure status to choose.

Missing IDs

Do not immediately ask the user for app IDs, function IDs, or run IDs.

Try, in order:

Dev Server MCP tools, if available.
The user's prompt, pasted dashboard URLs, logs, alert text, or stack traces.
Repository config and Inngest serve definitions.
Event ID lookup with
```
get-event-runs
```
.
Current CLI help to see if discovery commands such as
```
get-functions
```
or
```
get-app
```
have appeared.

Ask the user for the ID only after those sources cannot provide it.

Mutating Operations

Read before write. List or fetch the relevant resource first, then mutate only when target and intent are clear.

Confirm before running these against Cloud unless the user already specified the account/environment and exact intent:

```
create-env
```
```
patch-env
```
```
create-webhook
```
```
sync-app
```
```
invoke-function
```
Broad or expensive
```
query-insights
```
calls

For repeatable invocation tests, use a stable idempotency key:

bash

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

For complex JSON, use

--body-file

to avoid quoting mistakes.

Insights

Use Insights when the question is analytic, when logs only give partial clues, or when the user asks about trends, frequency, volume, failures over time, or event/run data.

Start small:

bash

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"

Inspect generated SQL before running broad queries. Add limits and time windows when possible.

Output Handling

CLI output is JSON. Parse it structurally before making decisions.
Use
```
--raw
```
only when a downstream command needs exact response bodies.
If responses are paginated and
```
page.hasMore
```
is true, continue with
```
--cursor
```
when complete results are needed.
Treat missing
```
data
```
on list responses as an empty list unless an error is present.
Redact secrets, webhook URLs, token values, and sensitive payload fields in summaries.

Drift Handling

The CLI is beta. If behavior differs from this skill:

Run top-level and command-specific help.
Check
```
https://api-docs.inngest.com/llms.txt
```
.

Check

https://api-docs.inngest.com/api-specs/v2.json

Use the
```
inngest-api
```
skill for raw REST API fallback.

Some launch material may mention aliases such as

get-run

invoke-function-by-slug

. Use them only if current

api --help

exposes them. If absent, use

get-function-run

and

invoke-function

inngest-api-cli

NPX Install

Tags

SKILL.md Content

Inngest API CLI

First Move

Target Rules

Local Development

Command Routing

Debug a Run

Missing IDs

Mutating Operations

Insights

Output Handling

Drift Handling