System Commands

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

`omni config`

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

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:

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

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

omni events metrics              # Processing metrics
omni events analytics            # Event analytics summary
omni events timeline <person-id> # Event timeline for a person

Replay

omni events replay               # Start, list, or manage replay sessions

`omni batch`

Batch processing for media transcription and text extraction at scale.

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.

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.

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.

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`)

omni turns list --status open --limit 20

`omni turns get`

Retrieve a single turn by its ID.

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

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

omni turns close-all --confirm --reason "maintenance window"

`omni turns stats`

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

omni turns stats

`omni replay`

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

omni replay <instanceId> [options]

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

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

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)

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

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:

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.

omni completions [shell]

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

omni completions bash >> ~/.bashrc
omni completions zsh >> ~/.zshrc

`omni dead-letters`

Inspect and manage failed events that could not be processed.

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.

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`)

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.

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

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

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.

Server lifecycle

install, start, stop, restart, doctor, update.

Events & Analytics

Full reference for omni events list, stream, replay, analytics.

Debug

Step-by-step troubleshooting commands and recipes.

Webhooks

Configure outbound event delivery to external services.

Getting Started

Core Concepts

CLI Reference

Architecture

System

System Commands

`omni config`

`omni events`

List and Search

Analytics

Replay

`omni batch`

`omni prompts`

`omni journey`

`omni turns`

Subcommands

`omni turns list`

`omni turns get`

`omni turns close`

`omni turns close-all`

`omni turns stats`

`omni replay`

`omni auth`

Subcommands

`omni settings`

Service Management

Advanced / Debugging

`omni completions`

`omni dead-letters`

`omni logs`

`omni payloads`

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

Global Flags

See also

Server lifecycle

Events & Analytics

Debug

Webhooks

​System Commands

​omni config

​omni events

​List and Search

​Analytics

​Replay

​omni batch

​omni prompts

​omni journey

​omni turns

​Subcommands

​omni turns list

​omni turns get

​omni turns close

​omni turns close-all

​omni turns stats

​omni replay

​omni auth

​Subcommands

​omni settings

​Service Management

​Advanced / Debugging

​omni completions

​omni dead-letters

​omni logs

​omni payloads

​Payload stages: webhook_raw, agent_request, agent_response, channel_send, error.

​Global Flags

​See also

Server lifecycle

Events & Analytics

Debug

Webhooks

System Commands

`omni config`

`omni events`

List and Search

Analytics

Replay

`omni batch`

`omni prompts`

`omni journey`

`omni turns`

Subcommands

`omni turns list`

`omni turns get`

`omni turns close`

`omni turns close-all`

`omni turns stats`

`omni replay`

`omni auth`

Subcommands

`omni settings`

Service Management

Advanced / Debugging

`omni completions`

`omni dead-letters`

`omni logs`

`omni payloads`

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

Global Flags

See also