OmniRoute/docs/CLI-TOOLS.md

CLI Tools Setup Guide — OmniRoute

This guide explains how to install and configure all supported AI coding CLI tools to use OmniRoute as the unified backend, giving you centralized key management, cost tracking, model switching, and request logging across every tool.

---

How It Works

Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
           │
           ▼  (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)

---

Supported Tools (Dashboard Source of Truth)

The dashboard cards in /dashboard/cli-tools are generated from src/shared/constants/cliTools.ts. Current list (v3.0.0-rc.16):

Tool	ID	Command	Setup Mode	Install Method
Claude Code	claude	claude	env	npm
OpenAI Codex	codex	codex	custom	npm
Factory Droid	droid	droid	custom	bundled/CLI
OpenClaw	openclaw	openclaw	custom	bundled/CLI
Cursor	cursor	app	guide	desktop app
Cline	cline	cline	custom	npm
Kilo Code	kilo	kilocode	custom	npm
Continue	continue	extension	guide	VS Code
Antigravity	antigravity	internal	mitm	OmniRoute
GitHub Copilot	copilot	extension	custom	VS Code
OpenCode	opencode	opencode	guide	npm
Kiro AI	kiro	app/cli	mitm	desktop/CLI

CLI fingerprint sync (Agents + Settings)

/dashboard/agents and Settings > CLI Fingerprint use src/shared/constants/cliCompatProviders.ts. This keeps provider IDs aligned with CLI cards and legacy IDs.

CLI ID	Fingerprint Provider ID
kilo	kilocode
copilot	github
claude / codex / antigravity / kiro / cursor / cline / opencode / 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 18+:

# 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

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

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)
kiro-cli --version   # 1.x.x

---

Step 3 — Set Global Environment Variables

Add to ~/.bashrc (or ~/.zshrc), then run source ~/.bashrc:

# 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/v1"
export ANTHROPIC_API_KEY="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

# Via CLI:
claude config set --global api-base-url http://localhost:20128/v1

# Or create ~/.claude/settings.json:
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
{
  "apiBaseUrl": "http://localhost:20128/v1",
  "apiKey": "sk-your-omniroute-key"
}
EOF

Test: claude "say hello"

---

OpenAI Codex

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

mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF
[provider.openai]
base_url = "http://localhost:20128/v1"
api_key = "sk-your-omniroute-key"
EOF

Test: opencode

---

Cline (CLI or VS Code)

CLI mode:

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:

kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key

VS Code settings:

{
  "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:

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)

# 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

---

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

---

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 tool is detected as installed)
5. Or copy the generated config snippet manually

---

Built-in Agents: Droid & OpenClaw

Droid and OpenClaw 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

---

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	DALL-E, 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	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 <command>
kiro-cli: not found	Not in PATH	export PATH="$HOME/.local/bin:$PATH"

---

Quick Setup Script (One Command)

# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
OMNIROUTE_URL="http://localhost:20128/v1"
OMNIROUTE_KEY="sk-your-omniroute-key"

npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode

# Kiro CLI
apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash

# Write configs
mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue

cat > ~/.claude/settings.json   <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
cat > ~/.codex/config.yaml      <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
cat >> ~/.bashrc << EOF
export OPENAI_BASE_URL="$OMNIROUTE_URL"
export OPENAI_API_KEY="$OMNIROUTE_KEY"
export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
EOF

source ~/.bashrc
echo "✅ All CLIs installed and configured for OmniRoute"