inngest-api

name	inngest-api
description	Use when inspecting or operating Inngest accounts, environments, keys, webhooks, app syncs, function invocations, runs, or traces through the Inngest CLI alpha REST API wrapper. Covers `npx inngest-cli@latest alpha api`, Cloud Production with `--prod`, local/custom API targets, authentication environment variables, safe secret handling, JSON body flags, and run/debug workflows.

Inngest API CLI

Use the alpha API CLI when the user needs account/environment operations, webhook management, app syncs, direct function invocation, or Cloud/local run inspection from Codex.

Because this command is alpha, verify the current interface before relying on memorized flags:

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

If the user asks about CLI agent experience, product friction, or why an agent is stuck, also read agent-friction.md.

Secret Handling

• Prefer credentials from environment variables: INNGEST_API_KEY, INNGEST_SIGNING_KEY, and INNGEST_ENV.
• Do not write keys into source files, docs, committed .env files, or command examples.
• Avoid --api-key <secret> in shell commands because it exposes the key in the transcript and process list.
• If the user must provide a key interactively, ask them to set INNGEST_API_KEY in their shell/session and confirm when it is available.
• Never print API keys, event keys, or signing keys in the final answer. When listing key resources, redact sensitive token values.

Targeting

By default, the command targets the local dev server.

# Local dev server
npx inngest-cli@latest alpha api health

# Inngest Cloud Production
npx inngest-cli@latest alpha api --prod get-account

# Branch/customer environment in Cloud
INNGEST_ENV=staging npx inngest-cli@latest alpha api --prod get-webhooks

# Custom API origin
npx inngest-cli@latest alpha api --api-host http://127.0.0.1 --api-port 8288 health

Common target/auth flags:

• --prod: target Inngest Cloud Production unless --api-host or --api-port is set.
• --api-host, --api-port: target a custom API server.
• --config: read target configuration from an Inngest config file.
• --timeout: adjust HTTP timeout.
• --env: send X-Inngest-Env, or use INNGEST_ENV.
• --api-key: Bearer token, or use INNGEST_API_KEY.
• --signing-key: Bearer token, or use INNGEST_SIGNING_KEY.
• --raw: print the response body without JSON formatting.

For env-scoped write operations, do not rely on implicit production targeting. Set INNGEST_ENV or pass --env explicitly and confirm the target environment before running create-webhook, sync-app, invoke-function, or patch-env.

Command Map

Account and environment:

• health: GET /health
• get-account: GET /account
• get-account-envs: GET /envs, supports --cursor and --limit
• create-env: POST /envs, supports --id, --name, --body, --body-file
• patch-env: PATCH /envs/{id}, supports --id, --is-archived, --body, --body-file

Keys and webhooks:

• get-account-event-keys: GET /keys/events, supports --cursor, --limit
• get-account-signing-keys: GET /keys/signing, supports --cursor, --limit
• get-webhooks: GET /env/webhooks, supports --cursor, --limit
• create-webhook: POST /env/webhooks, supports --name, --event-filter, --transform, --response, --body, --body-file

Apps, functions, and runs:

• sync-app: POST /apps/{app_id}/syncs, supports --app-id, --url, --body, --body-file
• invoke-function: POST /apps/{app_id}/functions/{function_id}/invoke, supports --app-id, --function-id, --data, --idempotency-key, --body, --body-file
• get-function-run: GET /runs/{run_id}, supports --run-id, --include-output
• get-function-trace: GET /runs/{run_id}/trace, supports --run-id, --include-output

Current discovery limitation: the alpha CLI does not expose list-apps, list-functions, or list-runs. If the user has not provided the required app_id, function_id, or run_id, first explain that the CLI cannot discover those IDs yet and ask for the ID or an alternate source such as the dashboard.

Workflows

Authenticated Smoke Test

When validating a provided API key or a new CLI install, start with low-risk read-only calls:

npx inngest-cli@latest alpha api --prod get-account
npx inngest-cli@latest alpha api --prod get-account-envs --limit 5

These confirm that authentication, Cloud targeting, and account/environment access work before making changes such as app syncs, webhooks, or invocations.

Inspect a Failed Production Run

1. Confirm the user has provided INNGEST_API_KEY through the environment, not in source files or visible command text.

2. If using a branch environment, set or pass INNGEST_ENV.

3. Fetch run metadata first:

   npx inngest-cli@latest alpha api --prod get-function-run --run-id <run_id>
   

4. Fetch the trace when step-level detail is needed:

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

5. Summarize failed steps, retry state, error messages, and likely code changes. Do not paste large raw traces unless the user asks.

Sync an App

Use sync-app when validating Cloud registration for an app URL and you already know the app ID. The current command shape is a re-sync for an existing app, not a first-time "register this serve URL" workflow.

npx inngest-cli@latest alpha api --prod sync-app --app-id <app_id> --url https://example.com/api/inngest

After sync, inspect the response for registration errors and compare them to the project's serve() endpoint, INNGEST_SIGNING_KEY, and deployed URL.

Invoke a Function

Use direct invocation for manual smoke tests or operational one-offs.

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

Prefer stable idempotency keys for repeatable tests. For complex payloads, use --body-file to avoid escaping mistakes.

Manage Webhooks

Before creating a webhook, list existing webhooks to avoid duplicates:

npx inngest-cli@latest alpha api --prod get-webhooks

For create-webhook, prefer a body file when transforms, filters, or response templates contain quotes or multiline strings.

Output Handling

• Default output is formatted JSON. Use --raw only when a downstream tool needs the exact response body.
• Parse JSON with a structured tool when making decisions from CLI output.
• Keep terminal summaries concise: account/env names, IDs, statuses, and actionable errors are usually enough.
• Paginated list responses include a page object. If page.hasMore is true, continue with --cursor <cursor> when the user needs complete results.
• Empty list responses may omit data; treat a missing data field as an empty list unless an error is present.
• Webhook URLs and decrypted signing keys are secrets. Redact them in summaries and never write them to docs, source files, or committed fixtures.

Agent Experience Notes

The CLI is suitable for Codex usage because common failure modes are concise and actionable:

• Missing or invalid Cloud auth returns 401 Unauthorized with access_denied; first verify a key was actually provided, then ask the user to provide or rotate INNGEST_API_KEY through the environment.
• Missing required path flags fail before a network request, for example missing required --run-id.
• A missing local dev server explains that inngest dev should be started or --prod should be used for Cloud.
• Unknown environments return 404 Not Found with env_not_found; list environments with get-account-envs before retrying.
• --raw returns compact JSON and is still parseable; prefer default formatted JSON for human summaries.
• Subcommand --help may hide inherited target/auth flags; check the top-level alpha api --help when target or auth behavior is unclear.

Treat create-env, patch-env, create-webhook, sync-app, and invoke-function as mutating or side-effecting operations. Use read-only checks first, then confirm intent and target environment before running them.

This Repository

These upstream Inngest instructions are vendored for agent tooling and integration work in this monorepo.

Repository Triggers

Use this skill when inngest-api matches the current Inngest task. If the right skill is unclear, start with docs/ai/skills/inngest/SKILL.md.

Repository Workflow

1. Confirm whether the request is agent-tooling guidance or product runtime integration.
2. Use inngest-brownfield-audit before changing existing app workflows or fragile background work.
3. Follow this upstream guidance under OpenSpec, root AGENTS.md, repo rulebooks, framework docs, and runtime evidence.
4. Keep runtime packages, app code, migrations, and INNGEST_* env requirements out of agent-tooling-only changes.

Repository Checklist

• The task has explicit product-runtime scope before adding Inngest app code or dependencies.
• Existing workflows were audited before introducing or changing durable workflow behavior.
• Any MCP usage is backed by a running Inngest dev server on the configured port.
• Upstream source and license attribution remain documented in docs/ai/skills/inngest/references/upstream.md.