IntroductionLocal developmentAI and MCP

Use the CLI with coding agents

Coding agents like Claude Code, Cursor, and Codex can use the Inngest CLI to pull real execution data when debugging or iterating on your functions. Instead of guessing what happened, the agent reads the actual trace.

Prerequisites

  • Inngest CLI: npx inngest-cli@latest
  • An Inngest account for Cloud access
  • A coding agent that can run shell commands

1. Sign in with OAuth

Run this in the environment where your coding agent runs shell commands:

npx inngest-cli@latest login

Complete the browser approval yourself. Choose your account, environment access, permissions, and session duration. Grant read access to the resources the agent needs to inspect, such as apps, functions, events, and runs. Add write access only if it needs to change Cloud data.

The CLI stores the OAuth credentials in your operating system's credential store and refreshes access tokens automatically. The agent's CLI commands use that login. OAuth scopes restrict each operation to the approved permissions and your current account role.

Use npx inngest-cli@latest auth status to check the login and npx inngest-cli@latest logout to revoke it. For a terminal without a browser, use login --no-browser and open the displayed URL yourself.

API keys remain an option for CI or unattended agents: set INNGEST_API_KEY to a key with the required access. An API key overrides the stored OAuth login, so unset INNGEST_API_KEY when switching to OAuth. See CLI authentication for details. Local Dev Server commands do not require Cloud authentication.

2. Add Inngest context to your agent

Tell the agent how to use the CLI. Add this to your project's CLAUDE.md, .cursorrules, or equivalent:

## Inngest debugging

Use the Inngest CLI to inspect function runs and traces:

- Get a run: `npx inngest-cli@latest api --prod --env production get-function-run <run_id>`
- Get a trace: `npx inngest-cli@latest api --prod --env production get-function-trace <run_id> --include-output`
- Get runs from an event: `npx inngest-cli@latest api --prod --env production get-event-runs <event_id> --include-output --limit 5`
- Invoke locally: `npx inngest-cli@latest api invoke-function <app_id> <function_id> --data '{...}'`

Output is JSON. Use jq to filter.
Cloud commands use the stored OAuth login unless INNGEST_API_KEY or an explicit key flag overrides it.
Set --env to the intended environment.
If access is denied, ask the user to review the session's permissions.

The agent now knows to reach for the CLI when it needs execution context.

3. Debug a failing function

When a function fails, point the agent at the run ID:

"The run 01ABC123 is failing in production. Use the Inngest CLI to get the trace and figure out which step is broken."

The agent runs:

npx inngest-cli@latest api --prod --env production get-function-trace 01ABC123 --include-output

It reads the trace, identifies the failing step, sees the error output, and proposes a fix with real context instead of guessing.

4. Test the fix

After the agent makes a code change, it can invoke the function locally against the dev server:

npx inngest-cli@latest api invoke-function my-app process-order \
  --data '{"orderId": "test-123"}'

Then check the result:

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

The agent verifies its own fix without leaving the terminal.

Why this matters

Without the CLI, an agent debugging an Inngest function has to guess what happened based on code alone. With the CLI, it reads the actual execution trace: which steps ran, which failed, what the error was, and what the output looked like. The feedback loop gets tighter.

This also means the agent can pull production data to reproduce issues locally, compare expected vs actual output, and verify fixes before pushing.

Next steps