FreePublished on GitHubEnglish overview

cli-serve

Start, stop, and restart the OmniRoute server from the command line. Configure its port, background operation, automatic recovery, and system tray integration, or open the dashboard to manage the running server.

OriginalShow the original 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.

cheaper-inference/OmniRoute

Works withCloudflare

AI rating90/ 100 See how to install

Good for

Starting the server on a chosen port
Running the server in the background with automatic recovery
Stopping or restarting the server
Opening the dashboard and configuring automatic startup

Overview

What it does

cli-serve controls the OmniRoute server from the command line, including starting, stopping, and restarting it. With serve, you can configure the port, daemon mode for background operation, automatic recovery, restart limits, and system tray display. Use dashboard to open the management interface. The skill also includes procedures for initial setup, diagnostics, automatic startup, backups, and checking logs.

When it helps

Use it when you want to run a local server on a particular port or start it without automatically opening a browser. It also helps configure continued operation and perform initial setup without interactive prompts for CI or Docker environments.

Example requests

“Start OmniRoute on port 3000 without opening a browser.”
“Start it in daemon mode and specify the restart limit for automatic recovery.”
“Restart the server and open the dashboard.”

Notes

The omniroute CLI is required. The stated Node.js requirement is version 22.22.2 or later, or 24 or later. Commands that communicate with the server require a connection URL and API key. The default connection URL is http://localhost:20128. Operations such as creating tunnels may require the corresponding external tools.

This overview was written by AI (OpenAI Codex) from the public SKILL.md. Check the original below for the exact behavior.

Objective evaluation

AI rated this skill on four points using only the contents of its SKILL.md. Stars and popularity are not taken into account.

Clear instructionsIs it clear when to use it and what it does?: AGoodIt states the purposes of serve, stop, restart, and dashboard and identifies server operation settings.
Concrete stepsAre steps, inputs, outputs, and examples spelled out?: AGoodIt provides startup and setup command examples, connection environment variables, and diagnostic check items.
SafetyAre sending data, deleting files, and running commands disclosed?: BPartly lackingIt covers stopping, restoring, and startup registration, but omits pre-execution checks and the scope of data overwritten during restoration.
Easy setupDoes it need few tools or API keys, and are they documented?: AGoodIt explains npm installation, Node.js requirements, and configuration of the server URL and API key.

The total counts each point as A = 25, B = 15, C = 5. Rated by AI (OpenAI Codex) as of Oct 22, 2026. Treat it as a guide and read the original before installing.

Disagree? Request a re-evaluation

Files included (1)

SKILL.md10.1 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

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

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

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:

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

Backup & restore

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

Autostart (system tray / startup)

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:

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

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

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

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

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

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

More skills from this repository

cli-a2a

FreeSummaryAI rating 90

Use the command line to send tasks to OmniRoute's A2A server, which supports communication between agents. Inspect execution history and logs, monitor or cancel tasks, and interactively test the JSON-RPC 2.0 communication protocol.

Check server status and available skills
Invoke a skill with JSON input
Inspect task history and logs