relay inspect

Loads your relay.ts and displays an execution's status, step history, and logs. Doesn't require the app to be running.

Usage

relay inspect <eventId|executionId> [--json] [--history] [--dir <path>]

Arguments

Argument	Description
`<eventId\|executionId>`	Either an event ID (from `relay trigger` or webhook) or an execution ID (from a previous `relay inspect` output)

Options

Flag	Default	Description
`--json`	false	Output structured JSON instead of human-readable text
`--history`	false	Show every step attempt (full audit trail); default shows only the latest attempt per step
`--dir`	current directory	Directory containing `relay.ts`

Requirements

A relay.ts in the target directory, exporting relay (see relay init)

Examples

Basic inspection

$ relay inspect evt_abc123xyz

Execution evt_abc123xyz
  event:      stripe.charge.succeeded (evt_abc123xyz)
  status:     ✔ completed (attempt 1)
  duration:   234ms

Steps:
  ✔ record-payment completed
  ✔ calculate-fee completed
  ✔ send-receipt completed
  ✔ notify-fulfillment completed

Logs:
  [system] [info] retrying (attempt 2, scheduled)
  [handler] [info] recorded payment
  [handler] [info] calculated platform fee
  [handler] [info] sent receipt email
  [handler] [info] notified fulfillment

With full step history

If a step failed once before succeeding, --history shows all attempts:

$ relay inspect evt_abc123xyz --history

Execution evt_abc123xyz
  event:      stripe.charge.succeeded (evt_abc123xyz)
  status:     ✔ completed (attempt 2)
  duration:   500ms

Steps (full history):
  ✖ send-receipt failed - receipt email provider timed out (attempt 1)
  ✔ send-receipt completed (attempt 2)

JSON output

$ relay inspect evt_abc123xyz --json

{
  "execution": {
    "id": "exec_...",
    "eventId": "evt_abc123xyz",
    "eventType": "stripe.charge.succeeded",
    "status": "completed",
    "attempt": 1,
    "createdAt": "2024-01-15T10:30:45.123Z",
    "completedAt": "2024-01-15T10:30:46.357Z",
    "eventData": { ... }
  },
  "steps": [
    {
      "id": "step_...",
      "executionId": "exec_...",
      "name": "record-payment",
      "status": "completed",
      "output": { "chargeId": "ch_1234", "amount": 1000 },
      "createdAt": "2024-01-15T10:30:45.200Z"
    },
    ...
  ],
  "logs": [
    {
      "id": "log_...",
      "executionId": "exec_...",
      "level": "info",
      "source": "handler",
      "message": "recorded payment",
      "createdAt": "2024-01-15T10:30:45.250Z"
    },
    ...
  ]
}

Finding an execution by event ID

If you have an event ID from a webhook (e.g., a Stripe event ID or GitHub delivery ID), just pass it:

relay inspect evt_1234567890abcdef

The command automatically looks up by both event ID and execution ID, so either works.

Understanding the output

Execution header:

event: Event type and ID
status: Completed, failed, or pending, plus attempt number
duration: Time from creation to completion
replayed from (if applicable): The source execution this was replayed from
error (if failed): Error message from the handler

Steps:

Status icon (✔/✖), step name, status, and error message if it failed
Without --history: only the latest attempt per step name
With --history: every attempt, in chronological order

Logs:

[source] — system (runtime lifecycle) or handler (your ctx.log calls)
[level] — debug, info, warn, error
Message and optional structured data

Replayed executions

If an execution was created by relay replay, the output includes:

Execution exec_new456
  event:      stripe.charge.succeeded (evt_old123)
  status:     ✔ completed (attempt 1)
  replayed from: exec_old123

This links back to the original execution for audit purposes.

relay inspect

On this page