Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/cli-serve
# Save SKILL.md to ~/.claude/skills/cli-serve/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.