# Inngest API

> Inngest API is an Agent Skill for apps & automation published in the Asymmetric-al/core repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `inngest-api`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/Asymmetric-al/core/blob/HEAD/.claude/skills/inngest-api/SKILL.md
- Repository: Asymmetric-al/core (375 GitHub stars when collected)

## SKILL.md

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

```bash
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](references/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.

```bash
# 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:

```bash
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:

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

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

   ```bash
   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.

```bash
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.

```bash
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:

```bash
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`.

---

Source: https://www.openparable.com/skill/apps-automation/inngest-api (OpenParable). Cite the canonical URL above.
