--- 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. --- ## 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 ` - `--tui` **Example:** ```bash omniroute dashboard ``` ### `restart` **Flags:** - `--port ` **Example:** ```bash omniroute restart ``` ### `serve` **Flags:** - `--port ` - `--no-open` - `--daemon` - `--log` - `--no-recovery` - `--max-restarts ` - `--tray` - `--no-tray` **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 ≥20.20.2, ≥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 ` | Override server URL for this invocation | | `--api-key ` | Override API key for this invocation | | `--output ` | 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 ` | 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](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md) 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 # 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 # 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 # Get a single env var value omniroute env set # 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 # 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`