Cli Serve
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.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Cli Serve when an AI agent needs a reusable SKILL.md workflow for this job: 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.
When not to use it
Skip Cli Serve when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cli-serve # Save SKILL.md to ~/.claude/skills/cli-serve/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cli-serve/SKILL.md. For a shared project, commit the folder at .claude/skills/cli-serve/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cli Serve skill for this task: Use Cli Serve when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
<!-- 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
```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>` - `--headless` - `--tray` - `--no-tray` - `--ready-timeout <ms>` - `--tls-cert <path>` - `--tls-key <path>`
**Example:**
```bash omniroute serve ```
### `stop`
**Flags:**
- `--port <port>`
**Example:**
```bash 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
```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 | | ---------------------------------- | --------------------------------------------------------------------------------------------- | | Backup & restore | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | Provider & key management | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-providers/SKILL.md | | Cloud agents (`omniroute cloud …`) | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | Evals & benchmarking | https://raw.githubusercontent.com/cheaper-inference/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
```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` <!-- skill:custom-end -->
Intended uses
- Use Cli Serve when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.