Debug a function run from your terminal

This guide walks you through finding a failed run, pulling its trace, and identifying which step broke. You do this entirely from the terminal using the Inngest CLI.

Prerequisites

  • Inngest CLI: npx inngest-cli@latest
  • An Inngest account with access to the Cloud environment you want to inspect

Sign in with OAuth:

npx inngest-cli@latest login

In the browser, choose your account and environment access, then grant read access to runs for this guide. OAuth limits the CLI to the approved permissions and your current account role. API keys are also supported for unattended scripts; see CLI authentication.

The examples below select production explicitly. Replace it with your environment's slug. Local Dev Server commands do not require Cloud authentication.

1. Get the run summary

You have a run ID from a log, alert, or the dashboard. Fetch the summary:

npx inngest-cli@latest api --prod --env production get-function-run 01KTCTWT8XDEGWDMVX3Q9M69ND

The response shows the run's status, function, timing, and trigger:

{
  "data": {
    "id": "01KTCTWT8XDEGWDMVX3Q9M69ND",
    "status": "FAILED",
    "function": {
      "name": "process-order",
      "slug": "my-app-process-order"
    },
    "queuedAt": "2026-06-05T21:26:44.765Z",
    "endedAt": "2026-06-05T21:26:45.954Z",
    "durationMs": "1096"
  }
}

The run failed. Pull the trace to see which step broke.

2. Fetch the trace

The trace shows every step in the run with its status, timing, and output:

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

The response is a tree of spans. Each span is a step. Look for the one with a failed status:

{
  "data": {
    "runId": "01KTCTWT8XDEGWDMVX3Q9M69ND",
    "rootSpan": {
      "name": "process-order",
      "status": "FAILED",
      "children": [
        {
          "name": "validate-input",
          "status": "COMPLETED",
          "stepOp": "RUN",
          "durationMs": "12"
        },
        {
          "name": "charge-card",
          "status": "COMPLETED",
          "stepOp": "RUN",
          "durationMs": "340"
        },
        {
          "name": "create-shipment",
          "status": "FAILED",
          "stepOp": "RUN",
          "durationMs": "744",
          "output": {
            "error": "shipping API returned 503"
          }
        }
      ]
    }
  }
}

The create-shipment step failed with a 503 from the shipping API. The validate-input and charge-card steps completed. You know exactly where it broke and what the error was.

3. Pipe to jq for quick filtering

Extract just the failed steps:

npx inngest-cli@latest api --prod --env production get-function-trace 01KTCTWT8XDEGWDMVX3Q9M69ND --include-output \
  | jq '[.data.rootSpan.children[] | select(.status == "FAILED")]'

4. Test a fix locally

Once you identify the issue, fix the code and test against your local dev server. The CLI targets the dev server by default:

# Invoke the function locally
npx inngest-cli@latest api invoke-function my-app process-order \
  --data '{"orderId": "test-123", "address": "123 Main St"}'

# Check the run
npx inngest-cli@latest api get-event-runs <event_id> --include-output

No --prod flag means it hits http://localhost:8288. The dev server must be running.

Next steps