> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug & Operations

> Hidden debug commands for troubleshooting Omni — dead letters, payloads, and system logs.

# Debug & Operations Commands

These commands are hidden by default and visible with the `--all` flag. They are used for troubleshooting and operations.

## Dead Letters

Manage failed events that could not be processed. Dead letters capture events that exhausted their retry budget — typically webhook deliveries, agent callbacks, or channel sends that repeatedly errored.

<Note>
  **When to use:** if a message appears stuck (received on the channel but never processed, or an outbound reply that never arrived), start with `omni dead-letters list` to see if the event landed in the dead-letter queue. Use `stats` for an aggregate health check, `get` to inspect the failure, and `retry` once the underlying issue is resolved. The `dead-letters` command is hidden from default `omni --help` — it is visible via `omni --all` and intended for operators and debugging.
</Note>

### `omni dead-letters list`

List dead letters with optional filters.

```bash theme={"dark"}
omni dead-letters list [options]
```

### `omni dead-letters get`

Get dead letter details.

```bash theme={"dark"}
omni dead-letters get <id>
```

### `omni dead-letters stats`

Get dead letter statistics.

```bash theme={"dark"}
omni dead-letters stats
```

### `omni dead-letters retry`

Retry processing a failed event.

```bash theme={"dark"}
omni dead-letters retry <id>
```

### `omni dead-letters resolve`

Mark a dead letter as resolved (acknowledged, no retry needed).

```bash theme={"dark"}
omni dead-letters resolve [options] <id>
```

### `omni dead-letters abandon`

Abandon a dead letter — stop all retry attempts.

```bash theme={"dark"}
omni dead-letters abandon <id>
```

```bash theme={"dark"}
# List recent failures
omni dead-letters list

# Check failure stats
omni dead-letters stats

# Retry a specific event
omni dead-letters retry dl-abc123

# Mark as resolved (no retry)
omni dead-letters resolve dl-abc123
```

***

## Payloads

Inspect event payloads at different processing stages.

### `omni payloads list`

List payloads for an event.

```bash theme={"dark"}
omni payloads list <eventId>
```

### `omni payloads get`

Get a specific payload stage.

```bash theme={"dark"}
omni payloads get <eventId> <stage>
```

Stages: `webhook_raw`, `agent_request`, `agent_response`, `channel_send`, `error`.

### `omni payloads delete`

Delete payloads for an event.

```bash theme={"dark"}
omni payloads delete [options] <eventId>
```

### `omni payloads config`

List or update payload storage configuration.

```bash theme={"dark"}
omni payloads config [options] [eventType]
```

### `omni payloads stats`

Get payload storage statistics.

```bash theme={"dark"}
omni payloads stats
```

```bash theme={"dark"}
# Inspect all payload stages for an event
omni payloads list evt-abc123

# Get the raw webhook payload
omni payloads get evt-abc123 webhook_raw

# Check storage stats
omni payloads stats
```