--- title: "CLI Tools — OmniRoute v3.8.0" version: 3.8.0 lastUpdated: 2026-05-13 --- # CLI Tools — OmniRoute v3.8.0 Last updated: 2026-05-13 OmniRoute integrates with two categories of CLI tools: 1. **External CLI integrations** — third-party CLIs (Cursor, Cline, Codex, Claude Code, Qwen Code, Windsurf, Hermes, Amp, etc.) that you point at OmniRoute's local OpenAI-compatible endpoint. 2. **Internal OmniRoute CLI** — commands bundled with the `omniroute` binary for server lifecycle, setup, diagnostics, and provider management. --- ## How It Works ``` Claude / Codex / OpenCode / Cline / KiloCode / Continue / Cursor / Windsurf / Hermes / Amp / Qwen │ ▼ (all point to OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (OmniRoute routes to the right provider) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ``` **Benefits:** - One API key to manage all tools - Cost tracking across all CLIs in the dashboard - Model switching without reconfiguring every tool - Works locally and on remote servers (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## 1. External CLI Integrations ### Source of Truth The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. The `omniroute setup` command can write config files automatically for the scriptable tools. ### Current Catalog (v3.8.0) | Tool | ID | Type / Config | Install / Access | Auth | | ------------------ | ------------- | ------------------- | ------------------------------------ | ----------------------------------- | | **Claude Code** | `claude` | env / settings.json | `npm i -g @anthropic-ai/claude-code` | API key (Anthropic gateway) | | **OpenAI Codex** | `codex` | custom (toml) | `npm i -g @openai/codex` | API key (OpenAI) | | **Factory Droid** | `droid` | custom | bundled / CLI | API key | | **Open Claw** | `openclaw` | custom | bundled / CLI | API key | | **Cursor** | `cursor` | guide (Cloud) | Cursor desktop app | API key (Cloud Endpoint) | | **Windsurf** | `windsurf` | guide | Windsurf desktop IDE | API key (BYOK) | | **Cline** | `cline` | custom / VS Code | `npm i -g cline` + VS Code ext | API key | | **Kilo Code** | `kilo` | custom / VS Code | `npm i -g kilocode` + VS Code ext | API key | | **Continue** | `continue` | guide (config.yaml) | VS Code extension | API key | | **Antigravity** | `antigravity` | MITM | OmniRoute built-in | API key (MITM proxy) | | **GitHub Copilot** | `copilot` | custom / VS Code | VS Code extension | API key (CLI fingerprint: `github`) | | **OpenCode** | `opencode` | guide (json) | `npm i -g opencode-ai` | API key (OpenAI-compatible) | | **Hermes** | `hermes` | guide (json) | install per docs | API key (OpenAI-compatible) | | **Amp CLI** | `amp` | guide (env) | install per Sourcegraph docs | API key (OpenAI-compatible) | | **Kiro AI** | `kiro` | MITM | Amazon Kiro IDE / CLI | API key (MITM proxy) | | **Qwen Code** | `qwen` | guide (json/env) | `npm i -g @qwen-code/qwen-code` | API key (OpenAI-compatible) | | **Custom CLI** | `custom` | custom-builder | any OpenAI-compatible client | API key | > Notes: > > - "Web wrappers" like ChatGPT/Claude/Grok/Perplexity browser sessions are not > listed here. OmniRoute can proxy them through the `chatgpt-web`, > `claude-web`, `grok-web`, `perplexity-web`, `blackbox-web`, > `muse-spark-web` provider connections, but those are **provider connections** > (configured under `/dashboard/providers`), not CLI tools. They do not surface > as cards under `/dashboard/cli-tools`. > - Tools marked **MITM** (Antigravity, Kiro) intercept the desktop app traffic > locally and require enabling the corresponding mitm endpoint in > `/dashboard/settings`. ### CLI fingerprint sync (Agents + Settings) `/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. This keeps provider IDs aligned with the CLI cards and legacy IDs. | CLI ID | Fingerprint Provider ID | | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `kilo` | `kilocode` | | `copilot` | `github` | | `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `windsurf` / `cline` / `opencode` / `hermes` / `amp` / `qwen` / `droid` / `openclaw` | same ID | Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. --- ### Step 1 — Get an OmniRoute API Key 1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`) 2. Click **Create API Key** 3. Give it a name (e.g. `cli-tools`) and select all permissions 4. Copy the key — you'll need it for every CLI below > Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Step 2 — Install CLI Tools All npm-based tools require Node.js 20.20.2+, 22.22.2+ or 24.x: ```bash # Claude Code (Anthropic) npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex # OpenCode npm install -g opencode-ai # Cline npm install -g cline # KiloCode npm install -g kilocode # Qwen Code (Alibaba) npm install -g @qwen-code/qwen-code # Kiro CLI (Amazon — requires curl + unzip) apt-get install -y unzip # on Debian/Ubuntu curl -fsSL https://cli.kiro.dev/install | bash export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc ``` **Verify:** ```bash claude --version # 2.x.x codex --version # 0.x.x opencode --version # x.x.x cline --version # 2.x.x kilocode --version # x.x.x (or: kilo --version) qwen --version # x.x.x kiro-cli --version # 1.x.x ``` --- ### Step 3 — Set Global Environment Variables Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: ```bash # OmniRoute Universal Endpoint export OPENAI_BASE_URL="http://localhost:20128/v1" export OPENAI_API_KEY="sk-your-omniroute-key" export ANTHROPIC_BASE_URL="http://localhost:20128" export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key" export GEMINI_BASE_URL="http://localhost:20128/v1" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > For a **remote server** replace `localhost:20128` with the server IP or domain, > e.g. `http://192.168.0.15:20128`. --- ### Step 4 — Configure Each Tool #### Claude Code ```bash # Create ~/.claude/settings.json: mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key" } } EOF ``` Use the unified Anthropic gateway root for Claude Code. Do not append `/v1` here. **Test:** `claude "say hello"` --- #### OpenAI Codex ```bash mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF model: auto apiKey: sk-your-omniroute-key apiBaseUrl: http://localhost:20128/v1 EOF ``` **Test:** `codex "what is 2+2?"` --- #### OpenCode ```bash mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF { "\$schema": "https://opencode.ai/config.json", "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key" }, "models": { "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" }, "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" }, "gemini-3-flash": { "name": "gemini-3-flash" } } } } } EOF ``` **Test:** `opencode` > Use `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` > to send thinking variants. --- #### Cline (CLI or VS Code) **CLI mode:** ```bash mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF { "apiProvider": "openai", "openAiBaseUrl": "http://localhost:20128/v1", "openAiApiKey": "sk-your-omniroute-key" } EOF ``` **VS Code mode:** Cline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1` Or use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**. --- #### KiloCode (CLI or VS Code) **CLI mode:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **VS Code settings:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` Or use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**. --- #### Continue (VS Code Extension) Edit `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Restart VS Code after editing. --- #### Kiro CLI (Amazon) ```bash # Login to your AWS/Kiro account: kiro-cli login # The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself. # Use kiro-cli alongside OmniRoute for other tools. kiro-cli status ``` For the **Kiro IDE** desktop app, use the MITM endpoint exposed by OmniRoute under `/dashboard/cli-tools → Kiro`. --- #### Qwen Code (Alibaba) Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`. > Qwen OAuth free tier was discontinued on 2026-04-15. Use OmniRoute with > `bailian-coding-plan` / `alibaba` / `alibaba-cn` / `openrouter` / `anthropic` / > `gemini` providers instead. **Option 1: Environment variables (`~/.qwen/.env`)** ```bash mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF OPENAI_API_KEY="sk-your-omniroute-key" OPENAI_BASE_URL="http://localhost:20128/v1" OPENAI_MODEL="auto" EOF ``` **Option 2: `settings.json` with `security.auth`** ```json // ~/.qwen/settings.json { "security": { "auth": { "selectedType": "openai", "apiKey": "sk-your-omniroute-key", "baseUrl": "http://localhost:20128/v1" } }, "model": { "name": "claude-sonnet-4-6" } } ``` **Option 3: Inline CLI flags** ```bash OPENAI_BASE_URL="http://localhost:20128/v1" \ OPENAI_API_KEY="sk-your-omniroute-key" \ OPENAI_MODEL="auto" \ qwen ``` > For a **remote server** replace `localhost:20128` with the server IP or domain. **Test:** `qwen "say hello"` --- #### Cursor (Desktop App) > **Note:** Cursor routes requests through its cloud. For OmniRoute integration, > enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. Via GUI: **Settings → Models → OpenAI API Key** - Base URL: `https://your-domain.com/v1` - API Key: your OmniRoute key --- #### Windsurf (Desktop IDE) > Official Windsurf docs currently describe BYOK for select Claude models plus > enterprise URL/token settings, not a generic custom OpenAI-compatible provider. > Test BYOK behavior in your environment before relying on this integration. 1. Open AI Settings inside Windsurf. 2. Select **Add custom provider** (OpenAI-compatible). 3. Base URL: `http://localhost:20128/v1` 4. API Key: your OmniRoute key 5. Pick a model from the OmniRoute catalog. --- #### Hermes ```json // Hermes config file { "provider": { "type": "openai", "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key", "model": "claude-sonnet-4-6" } } ``` --- #### Amp CLI (Sourcegraph) ```bash export OPENAI_API_KEY="sk-your-omniroute-key" export OPENAI_BASE_URL="http://localhost:20128/v1" amp --model "claude-sonnet-4-6" # Suggested shorthand aliases you can map locally: # g25p -> gemini/gemini-2.5-pro # g25f -> gemini/gemini-2.5-flash # cs45 -> cc/claude-sonnet-4-5-20250929 # g54 -> gemini/gemini-3.1-pro-high ``` --- ### Dashboard Auto-Configuration The OmniRoute dashboard automates configuration for most tools: 1. Go to `http://localhost:20128/dashboard/cli-tools` 2. Expand any tool card 3. Select your API key from the dropdown 4. Click **Apply Config** (if the tool is detected as installed) 5. Or copy the generated config snippet manually --- ### Built-in Agents: Droid & Open Claw **Droid** and **Open Claw** are AI agents built directly into OmniRoute — no installation needed. They run as internal routes and use OmniRoute's model routing automatically. - Access: `http://localhost:20128/dashboard/agents` - Configure: same combos and providers as all other tools - No API key or CLI install required --- ## 2. Internal OmniRoute CLI The `omniroute` binary (installed via `npm install -g omniroute` or bundled with the desktop app) provides commands beyond running the server. The full matrix is implemented in: - `bin/omniroute.mjs` — entry point, env loading, special-case dispatch (`--mcp`) - `bin/cli/program.mjs` — Commander program builder - `bin/cli/commands/.mjs` — one file per command/group, registered in `registry.mjs` - `bin/cli/output.mjs` — output formatters (json/jsonl/table/csv) - `bin/cli/runtime.mjs` — withRuntime helper (server-first/db-fallback) - `bin/cli/i18n.mjs` — t() helper with locales ### Server Lifecycle ```bash omniroute # Start server (default port 20128) omniroute --port 3000 # Override port omniroute --no-open # Don't auto-open browser omniroute --mcp # Start as MCP server (stdio transport) omniroute serve # Same as `omniroute` omniroute stop # Stop the running server omniroute restart # Restart the server omniroute dashboard # Open dashboard in default browser omniroute open # Alias for `dashboard` omniroute --version # Print version omniroute --help # Show all commands ``` ### Setup & Initialization ```bash omniroute setup # Interactive setup wizard omniroute setup --non-interactive # CI/automation mode (reads env vars + flags) omniroute setup --password '' # Set admin password directly omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Add and test a provider in one shot ``` Recognized environment variables for non-interactive setup: | Var | 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 the OmniRoute data directory | ### Diagnostics ```bash omniroute doctor # Check config, DB, ports, runtime, memory, liveness omniroute doctor --json # Machine-readable JSON omniroute doctor --no-liveness # Skip the HTTP health probe omniroute doctor --host 0.0.0.0 # Override liveness host omniroute doctor --liveness-url # Full health endpoint URL override ``` The doctor runs these checks: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory`, and `Server liveness`. It exits non-zero if any check is `fail`. ### Provider Management ```bash omniroute providers available # OmniRoute provider catalog omniroute providers available --search openai # Filter catalog by id/name/alias/category omniroute providers available --category api-key # Filter by category (api-key, oauth, free, ...) omniroute providers available --json # Machine-readable JSON omniroute providers list # Configured provider connections omniroute providers list --json omniroute providers test # Test one configured connection omniroute providers test-all # Test every active connection omniroute providers validate # Local-only structural validation ``` > `providers available` reads the OmniRoute catalog; `providers list/test/test-all/validate` > read the local SQLite database directly and do not require the server to be running. ### Recovery & Reset ```bash omniroute reset-password # Reset the admin password (legacy alias still works) omniroute reset-encrypted-columns # Show warning + dry-run for encrypted credential reset omniroute reset-encrypted-columns --force # Actually null out encrypted credentials in SQLite ``` ### Other subcommands These assume a running OmniRoute server, unless noted otherwise: ```bash omniroute status # Comprehensive runtime status omniroute logs # Stream request logs (--json, --search, --follow) omniroute config show # Display current configuration omniroute provider list # List available providers (alias of providers list) omniroute provider add # Register OmniRoute as a provider on a tool omniroute keys add | list | remove # Manage API keys omniroute models [provider] # List models (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Snapshot config + DB omniroute restore # Restore from a previous snapshot omniroute health # Detailed health (breakers, cache, memory) omniroute quota # Provider quota usage omniroute cache # Cache status omniroute cache clear # Clear semantic + signature caches omniroute mcp status | restart # MCP server status / restart omniroute a2a status | card # A2A server status / agent card omniroute tunnel list | create | stop # Manage tunnels (cloudflare/tailscale/ngrok) omniroute env show | get | set # Inspect / set env vars (temporary) omniroute test # Provider connectivity smoke test omniroute update # Check for updates omniroute completion # Generate shell completion ``` ### Common flags | Flag | Description | | ------------------- | ------------------------------------------------------ | | `--no-open` | Don't auto-open the browser on start | | `--port ` | Override the API port (default 20128) | | `--mcp` | Run as MCP server over stdio (for IDEs) | | `--non-interactive` | CI mode (no prompts; reads from env/flags) | | `--json` | Machine-readable JSON output (doctor, providers, etc.) | | `--help`, `-h` | Show command-specific help | | `--version`, `-v` | Print the installed version | --- ## Available API Endpoints | Endpoint | Description | Use For | | -------------------------- | ----------------------------- | --------------------------- | | `/v1/chat/completions` | Standard chat (all providers) | All modern tools | | `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | | `/v1/completions` | Legacy text completions | Older tools using `prompt:` | | `/v1/embeddings` | Text embeddings | RAG, search | | `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. | | `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | | `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | --- ## Troubleshooting | Error | Cause | Fix | | ------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------- | | `Connection refused` | OmniRoute not running | `omniroute serve` or `pm2 start omniroute` | | `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | | `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | | `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | | CLI shows "not installed" | Binary not in PATH | Check `which ` | | `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | | `doctor` reports SQLite incompatible | Wrong native binary | `cd app && npm rebuild better-sqlite3` | | `doctor` reports `STORAGE_ENCRYPTION_KEY` missing | Encrypted creds without key | Set `STORAGE_ENCRYPTION_KEY` or `omniroute reset-encrypted-columns --force` | --- ## Quick Setup Script (One Command) ```bash cat > my-setup.sh <<'EOF' #!/usr/bin/env bash set -euo pipefail # === Edit these === OMNIROUTE_URL="http://localhost:20128/v1" OMNIROUTE_ANTHROPIC_URL="http://localhost:20128" OMNIROUTE_KEY="sk-your-omniroute-key" # ================== # 1. Install the external CLIs npm install -g \ @anthropic-ai/claude-code \ @openai/codex \ opencode-ai \ cline \ kilocode \ @qwen-code/qwen-code # 2. Optional: Kiro CLI (needs unzip) if ! command -v unzip >/dev/null 2>&1; then sudo apt-get install -y unzip fi curl -fsSL https://cli.kiro.dev/install | bash # 3. Write the per-tool config files mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue ~/.qwen cat > ~/.claude/settings.json < ~/.codex/config.yaml < ~/.qwen/.env </dev/null; then cat >> ~/.bashrc <