System
System Commands
Commands for configuration, event querying, batch processing, prompt management, and diagnostics.
omni config
Manage CLI configuration — default instance, output format, API settings.
1234omni 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:
12omni 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
123omni events list # List recent events omni events list --instance <id> --limit 50 # Filter by instance omni events search <query> # Search events by content
Analytics
123omni events metrics # Processing metrics omni events analytics # Event analytics summary omni events timeline <person-id> # Event timeline for a person
Replay
1omni events replay # Start, list, or manage replay sessions
omni batch
Batch processing for media transcription and text extraction at scale.
12345omni 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.
1234omni 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.
12omni 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.
1omni 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) |
1omni turns list --status open --limit 20
omni turns get
Retrieve a single turn by its ID.
1omni 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 |
1omni 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 |
1omni turns close-all --confirm --reason "maintenance window"
omni turns stats
Show aggregate turn metrics: open count, total count, average duration, and timeout rate.
1omni turns stats
omni replay
Replay missed messages for an agent instance. Useful for recovering messages that arrived while an agent was offline.
1omni replay <instanceId> [options]
| Option | Description |
-s, --since <timestamp> | Replay messages received after this ISO 8601 timestamp (default: lastSeenAt, max 24h ago) |
12345# 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.
1omni 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) |
1234567891011# 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.
123omni 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:
12345omni 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.
1omni completions [shell]
| Argument | Description |
shell | Shell type: bash, zsh, fish |
12omni completions bash >> ~/.bashrc omni completions zsh >> ~/.zshrc
omni dead-letters
Inspect and manage failed events that could not be processed.
123456omni 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.
1omni 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) |
123omni 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.
12345omni 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.Ask AI about this page