/cli-serve

name: cli-serve
description: 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.

<!-- 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>`
• `--headless`
• `--tray`
• `--no-tray`
• `--ready-timeout <ms>`
• `--tls-cert <path>`
• `--tls-key <path>`

**Example:**

omniroute serve

`stop`

**Flags:**

• `--port <port>`

**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:

| Source | Variable / Flag | | -------- | ------------------------------------ | | Base URL | `OMNIROUTE_BASE_URL` or `--base-url` | | API key | `OMNIROUTE_API_KEY` or `--api-key` |

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

| Flag | Description | | ------------------- | -------------------------------------------------------- | | `--base-url <url>` | Override server URL for this invocation | | `--api-key <key>` | Override API key for this invocation | | `--output <format>` | Output format: `table` (default), `json`, `jsonl`, `csv` | | `--json` | Shorthand for `--output json` | | `--non-interactive` | Disable prompts — for CI / shell scripts | | `--no-open` | Don't auto-open the browser on start | | `--port <n>` | Override default port 20128 | | `--help`, `-h` | Show help for the current command | | `--version`, `-v` | Print the installed version |

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

| Capability | Skill | | ---------------------------------- | --------------------------------------------------------------------------------------------- | | Backup & restore | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | Provider & key management | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-providers/SKILL.md | | Cloud agents (`omniroute cloud …`) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | Evals & benchmarking | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-eval/SKILL.md |

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 the install and global-flags sections above.

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 ope