cli-serve

Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

bash

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

Subcommands

`dashboard`

Flags:

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

Example:

bash

omniroute dashboard

`restart`

Flags:

--port <port>

Example:

bash

omniroute restart

`serve`

Flags:

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

Example:

bash

omniroute serve

`stop`

Example:

bash

omniroute stop

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

bash

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

Requires Node.js ≥22.22.2 or ≥24.

Verify:

bash

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

bash

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

For a remote server:

bash

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:

bash

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

bash

# 1. Start server
omniroute

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

# 3. Verify everything is healthy
omniroute doctor

CLI capability skills

Capability	Skill
Server admin + backup	https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md
Provider & key management	https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md
Cloud agents (Codex / Devin / Jules)	https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md
Evals & benchmarking	https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-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 CLI entry-point skill for install + global flags.

Server lifecycle

bash

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

bash

omniroute setup                        # Step-by-step interactive setup

Non-interactive (CI / Docker)

bash

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

Environment variables for non-interactive setup:

Variable	Purpose
`OMNIROUTE_SETUP_PASSWORD`	Admin password (≥8 chars)
`OMNIROUTE_PROVIDER`	Provider id (e.g. `openai`, `anthropic`)
`OMNIROUTE_PROVIDER_NAME`	Display name for the connection
`OMNIROUTE_PROVIDER_BASE_URL`	Optional OpenAI-compatible base URL override
`OMNIROUTE_API_KEY`	Provider API key
`OMNIROUTE_DEFAULT_MODEL`	Optional default model
`DATA_DIR`	Override OmniRoute data directory

Diagnostics

bash

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:

bash

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

Backup & restore

bash

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

Autostart (system tray / startup)

bash

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

On Linux: creates a systemd user service (~/.config/systemd/user/omniroute.service) and enables linger so the service can start after reboot without a graphical login; on desktop sessions it also adds an XDG autostart entry with --tray. On macOS: LaunchAgent plist. On Windows: registry startup entry.

Tunnels (public URL)

Expose a local OmniRoute instance via a secure tunnel:

bash

omniroute tunnel list                  # List active tunnels
omniroute tunnel create cloudflare     # Start a Cloudflare Tunnel (free)
omniroute tunnel create tailscale      # Start a Tailscale funnel
omniroute tunnel create ngrok          # Start an ngrok tunnel
omniroute tunnel stop <id>             # Stop a running tunnel

The tunnel URL is printed and can be used as OMNIROUTE_BASE_URL from remote machines.

Config & environment

bash

omniroute config show                  # Display current effective configuration
omniroute env show                     # List all OmniRoute environment variables
omniroute env get <KEY>                # Get a single env var value
omniroute env set <KEY> <value>        # Set an env var (temporary — until restart)

Recovery

bash

omniroute reset-password               # Reset the admin password interactively
omniroute reset-encrypted-columns      # Dry-run: show encrypted credential columns
omniroute reset-encrypted-columns --force  # Null out encrypted credentials in SQLite

Use reset-encrypted-columns --force only if STORAGE_ENCRYPTION_KEY was lost and you need to re-enter all provider API keys.

Logs

bash

omniroute logs                         # Stream live request logs
omniroute logs --json                  # JSON log entries
omniroute logs --search <term>         # Filter by term
omniroute logs --follow                # Tail mode (keep streaming)

Update

bash

omniroute update                       # Check for a newer version and prompt to update

Errors

doctor shows STORAGE_ENCRYPTION_KEY missing → set the key in .env or run reset-encrypted-columns --force to wipe and re-enter credentials
doctor reports native binary fail → npm rebuild better-sqlite3 in the OmniRoute app directory
tunnel create cloudflare hangs → ensure cloudflared is installed: brew install cloudflare/cloudflare/cloudflared

Overview

Quick install

Subcommands

`dashboard`

`restart`

`serve`

`stop`

Setup

Install

Connection

Global flags

Output formats

Quick start: one-shot server + provider setup

CLI capability skills

Errors

Admin lifecycle

Server lifecycle

Setup & provisioning

Interactive wizard

Non-interactive (CI / Docker)

Diagnostics

Backup & restore

Autostart (system tray / startup)

Tunnels (public URL)

Config & environment

Recovery

Logs

Update

Errors

Autres Skills

cli-a2a

cli-backup-sync

cli-batches

cli-chat