CLI Serve

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

Overview

Start, stop, and restart the OmniRoute server from the CLI. Manage daemon mode, port configuration, auto-recovery, system tray integration, and the dashboard open shortcut.

Quick install

npm install -g omniroute   # or: npx omniroute
omniroute --version

Subcommands

dashboard

Flags:

• --url
• --port <port>
• --tui

Example:

omniroute dashboard

restart

Flags:

• --port <port>

Example:

omniroute restart

serve

Flags:

• --port <port>
• --no-open
• --daemon
• --log
• --no-recovery
• --max-restarts <n>
• --tray
• --no-tray
• --ready-timeout <ms>
• --tls-cert <path>
• --tls-key <path>

Example:

omniroute serve

stop

Example:

omniroute stop

<!-- skill:custom-start --> <!-- Aggregated from: omniroute-cli (setup + index), omniroute-cli-admin (lifecycle/setup/backup/tunnel) -->

Setup

The omniroute binary ships with the OmniRoute server. It is both the server launcher and a full management CLI with 250+ commands across 39 groups.

Install

npm install -g omniroute          # npm registry
# or: use the binary bundled with the desktop app

Requires Node.js ≥22.22.2 or ≥24.

Verify:

omniroute --version   # prints installed version
omniroute --help      # full command tree

Connection

Every CLI command that talks to the server reads two values:

Default base URL: http://localhost:20128

export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="sk-..."          # from Dashboard → API Manager

For a remote server:

export OMNIROUTE_BASE_URL="https://your-server.com"

Global flags

Output formats

All listing commands support --output:

omniroute combo list                      # human-readable table
omniroute combo list --output json        # JSON array
omniroute combo list --output jsonl       # one JSON object per line
omniroute combo list --output csv         # CSV with header row

Quick start: one-shot server + provider setup

# 1. Start server
omniroute

# 2. (First run) interactive setup wizard
omniroute setup

# 3. Verify everything is healthy
omniroute doctor

CLI capability skills

Errors

• Connection refused → server not running; run omniroute or omniroute serve
• 401 Unauthorized → wrong or missing API key
• command not found: omniroute → not in PATH; check npm root -g or re-install
• doctor reports SQLite incompatible → npm rebuild better-sqlite3 in the app directory

Admin lifecycle

Requires the omniroute CLI. See CLI entry-point skill for install + global flags.

Server lifecycle

omniroute                              # Start server (default port 20128)
omniroute serve                        # Explicit alias
omniroute --port 3000                  # Override port
omniroute --no-open                    # Don't auto-open browser
omniroute --mcp                        # Start as MCP server (stdio transport)

omniroute stop                         # Stop the running server
omniroute restart                      # Restart the server

omniroute dashboard                    # Open dashboard in browser
omniroute open                         # Alias for dashboard
omniroute status                       # Runtime status (uptime, requests, providers)

Setup & provisioning

Interactive wizard

omniroute setup                        # Step-by-step interactive setup

Non-interactive (CI / Docker)

omniroute setup --non-interactive \
  --password 'admin-password' \
  --add-provider \
  --provider openai \
  --api-key 'sk-...' \
  --test-provider

Environment variables for non-interactive setup:

Diagnostics

omniroute doctor                       # Full health check
omniroute doctor --json                # Machine-readable JSON
omniroute doctor --no-liveness         # Skip HTTP health probe
omniroute doctor --host 0.0.0.0        # Override liveness host
omniroute doctor --liveness-url <url>  # Full URL override

Checks performed: Config, Database, Storage/encryption, Port, Node runtime, Native binary (better-sqlite3), Memory, Server liveness.

Exit code is non-zero if any check fails — useful in CI:

omniroute doctor --json | jq '.checks[] | select(.status=="fail")'

Backup & restore

omniroute backup                       # Snapshot config + SQLite DB to ~/.omniroute/backups/
omniroute restore                      # Restore from a previous snapshot (interactive picker)

Autostart (system tray / startup)

omniroute autostart enable             # Register OmniRoute as a system startup item
omniroute autostart disable            # Remove startup registration
omniroute autostart status             # Show current autostart state