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

# System

> Configuration, events, batch processing, prompts, diagnostics, and service management.

# System Commands

Commands for configuration, event querying, batch processing, prompt management, and diagnostics.

## `omni config`

Manage CLI configuration — default instance, output format, API settings.

```bash theme={"dark"}
omni config list            # List all config values
omni config get <key>       # Get a value
omni config set <key> <val> # Set a value
omni config unset <key>     # Remove a value
```

Common settings:

```bash theme={"dark"}
omni config set instance <id>     # Set default instance
omni config set format json       # Default to JSON output
```

***

## `omni events`

Query the event log — message history, analytics, and replay.

### List and Search

```bash theme={"dark"}
omni events list                              # List recent events
omni events list --instance <id> --limit 50   # Filter by instance
omni events search <query>                    # Search events by content
```

### Analytics

```bash theme={"dark"}
omni events metrics              # Processing metrics
omni events analytics            # Event analytics summary
omni events timeline <person-id> # Event timeline for a person
```

### Replay

```bash theme={"dark"}
omni events replay               # Start, list, or manage replay sessions
```

***

## `omni batch`

Batch processing for media transcription and text extraction at scale.

```bash theme={"dark"}
omni batch list                         # List batch jobs
omni batch create [options]             # Create a processing job
omni batch status <job-id>              # Check job status
omni batch cancel <job-id>              # Cancel a running job
omni batch estimate [options]           # Estimate scope and cost
```

***

## `omni prompts`

Manage LLM prompt overrides for media processing. Omni uses prompts for image description, video description, document extraction, and gating decisions.

```bash theme={"dark"}
omni prompts list                       # List all prompts with override status
omni prompts get <name>                 # Show current prompt (image|video|document|gate)
omni prompts set <name> [value]         # Set override (reads stdin for multiline)
omni prompts reset <name>               # Clear override, revert to default
```

***

## `omni journey`

Message journey tracing — track a message through the full Omni pipeline for latency debugging.

```bash theme={"dark"}
omni journey show <correlation-id>      # Display journey timeline with timing bars
omni journey summary                    # Aggregated journey metrics
```

***

## `omni turns`

Admin turn management — inspect active conversation turns, force-close stuck turns, and view aggregate metrics.

```bash theme={"dark"}
omni turns [command]
```

### Subcommands

| Command      | Description                                      |
| ------------ | ------------------------------------------------ |
| `list`       | List turns with optional filters                 |
| `get <id>`   | Get a single turn by ID                          |
| `close <id>` | Admin force-close a turn                         |
| `close-all`  | Bulk close all open turns (requires `--confirm`) |
| `stats`      | Show aggregate turn metrics                      |

### `omni turns list`

List turns with optional filters.

| Option              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `--status <status>` | Filter by status: `open`, `done`, `timeout`                      |
| `--instance <id>`   | Filter by instance ID (aliases: `--instance-ids`, `--instances`) |
| `--chat <id>`       | Filter by chat ID                                                |
| `--agent <id>`      | Filter by agent ID                                               |
| `--limit <n>`       | Max results (default: `50`)                                      |
| `--offset <n>`      | Offset for pagination (default: `0`)                             |

```bash theme={"dark"}
omni turns list --status open --limit 20
```

### `omni turns get`

Retrieve a single turn by its ID.

```bash theme={"dark"}
omni turns get 7f3e1a2b-9c4d-4e5f-a6b7-8c9d0e1f2a3b
```

### `omni turns close`

Admin force-close a turn that is stuck open.

| Option            | Description                         |
| ----------------- | ----------------------------------- |
| `--reason <text>` | Close reason recorded with the turn |

```bash theme={"dark"}
omni turns close 7f3e1a2b-9c4d-4e5f-a6b7-8c9d0e1f2a3b --reason "stuck on upstream timeout"
```

### `omni turns close-all`

Bulk close every open turn. This is a destructive admin action and **requires the `--confirm` flag** — without it, the command exits with an error and takes no action.

| Option            | Description                                |
| ----------------- | ------------------------------------------ |
| `--confirm`       | **Required.** Confirm the bulk close.      |
| `--reason <text>` | Close reason recorded on every closed turn |

```bash theme={"dark"}
omni turns close-all --confirm --reason "maintenance window"
```

### `omni turns stats`

Show aggregate turn metrics: open count, total count, average duration, and timeout rate.

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

***

## `omni replay`

Replay missed messages for an agent instance. Useful for recovering messages that arrived while an agent was offline.

```bash theme={"dark"}
omni replay <instanceId> [options]
```

| Option                    | Description                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `-s, --since <timestamp>` | Replay messages received after this ISO 8601 timestamp (default: `lastSeenAt`, max 24h ago) |

```bash theme={"dark"}
# Replay missed messages since the agent's last seen time
omni replay wa-main

# Replay messages received after a specific timestamp
omni replay wa-main --since 2026-02-27T10:00:00Z
```

***

## `omni auth`

Manage API authentication — login, check status, logout, and recover credentials.

```bash theme={"dark"}
omni auth [command]
```

### Subcommands

| Command   | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| `login`   | Save API credentials                                                   |
| `status`  | Show current authentication status                                     |
| `logout`  | Clear stored credentials                                               |
| `recover` | Recover API key when `keyValid` shows `no` (requires local PM2 access) |

```bash theme={"dark"}
# Save credentials
omni auth login

# Check current auth status
omni auth status

# Clear stored credentials
omni auth logout

# Recover a broken API key
omni auth recover
```

***

## `omni settings`

Server-level settings management.

```bash theme={"dark"}
omni settings list [options]            # List all server settings
omni settings get <key>                 # Get a specific setting
omni settings set [options] <key> <value>  # Set a setting value
```

***

## Service Management

Start, stop, and restart the Omni server and NATS:

```bash theme={"dark"}
omni start      # Start Omni services (API + NATS)
omni stop       # Stop services
omni restart    # Restart services
omni status     # API health and connection info
omni update     # Update CLI to latest version
```

***

## Advanced / Debugging

These commands are hidden from default `omni --help` output (visible via `omni --help --all`). They are useful for troubleshooting, inspecting internals, and automating shell setup.

### `omni completions`

Generate shell completions for the Omni CLI.

```bash theme={"dark"}
omni completions [shell]
```

| Argument | Description                       |
| -------- | --------------------------------- |
| `shell`  | Shell type: `bash`, `zsh`, `fish` |

```bash theme={"dark"}
omni completions bash >> ~/.bashrc
omni completions zsh >> ~/.zshrc
```

***

### `omni dead-letters`

Inspect and manage failed events that could not be processed.

```bash theme={"dark"}
omni dead-letters list [options]          # List dead letters
omni dead-letters get <id>                # Get dead letter details
omni dead-letters stats                   # Dead letter statistics
omni dead-letters retry <id>              # Retry processing a dead letter
omni dead-letters resolve [options] <id>  # Mark as resolved
omni dead-letters abandon <id>            # Abandon retry attempts
```

***

### `omni logs`

View system logs with module and level filtering.

```bash theme={"dark"}
omni logs [options] [level]
```

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| `level`  | Log level filter: `debug`, `info`, `warn`, `error` |

| Option                | Description                              |
| --------------------- | ---------------------------------------- |
| `--modules <modules>` | Comma-separated module names to filter   |
| `--limit <n>`         | Limit results (default: `100`)           |
| `--process [service]` | Stream PM2 process logs (default: `api`) |
| `--follow`            | Stream live logs (only with `--process`) |

```bash theme={"dark"}
omni logs error --limit 50
omni logs --process api --follow
omni logs warn --modules webhook,agent
```

***

### `omni payloads`

Inspect raw event payloads at each processing stage — useful for debugging event pipeline issues.

```bash theme={"dark"}
omni payloads list <eventId>                # List payloads for an event
omni payloads get <eventId> <stage>         # Get a specific stage
omni payloads delete [options] <eventId>    # Delete payloads for an event
omni payloads config [options] [eventType]  # View/update storage config
omni payloads stats                         # Storage statistics
```

## Payload stages: `webhook_raw`, `agent_request`, `agent_response`, `channel_send`, `error`.

## Global Flags

These flags work with any command:

| Flag         | Description            |
| ------------ | ---------------------- |
| `--json`     | Output in JSON format  |
| `--no-color` | Disable colored output |

<Tip>
  Set `--json` once via `omni config set format json` to avoid retyping it on every command — useful when wiring CLI output into scripts.
</Tip>

<Warning>
  `omni payloads delete` and `omni config unset` are destructive — payloads can't be recovered, and unsetting a config key reverts to defaults silently. There's no undo or audit log.
</Warning>

## See also

<CardGroup cols={2}>
  <Card title="Server lifecycle" icon="server" href="/omni/cli/management">
    `install`, `start`, `stop`, `restart`, `doctor`, `update`.
  </Card>

  <Card title="Events & Analytics" icon="chart-line" href="/omni/cli/events">
    Full reference for `omni events list`, `stream`, `replay`, `analytics`.
  </Card>

  <Card title="Debug" icon="bug" href="/omni/cli/debug">
    Step-by-step troubleshooting commands and recipes.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/omni/cli/webhooks">
    Configure outbound event delivery to external services.
  </Card>
</CardGroup>