frouter

Free model router CLI — discover, ping, and configure free AI models for OpenCode / OpenClaw.

Install

npx frouter-cli
# or
npm i -g frouter-cli
# or
bunx frouter-cli
# or
bun install -g frouter-cli

Run

frouter

On first run, a setup wizard prompts for API keys (ESC to skip any provider).

First-run onboarding test (clean state)

Use an isolated temporary HOME to test onboarding from zero without deleting your real install/config:

npm run test:onboarding
npm run test:fresh-start

test:fresh-start launches interactive onboarding with:

• no ~/.frouter.json in the temp home
• provider env keys unset (NVIDIA_API_KEY, OPENROUTER_API_KEY)
• your real ~/.frouter.json untouched

Optional:

npm run test:fresh-start -- --keep-home

This keeps the temp HOME path after exit for inspection.

Providers

API key priority: environment variable → ~/.frouter.json → keyless ping (latency still shown).

NVIDIA_API_KEY=nvapi-xxx frouter
OPENROUTER_API_KEY=sk-or-xxx frouter

TUI

The interactive TUI pings all models in parallel every 2 seconds and shows live latency, uptime, and verdict.

Columns

Default ranking: availability first, then higher tier first (S+ → S → A+ …), then lower latency.

Keyboard shortcuts

Navigation

Actions

Sort (press to sort, press again to reverse)

Target picker

After pressing Enter on a model:

If OpenCode fallback remaps the provider (for example NIM Stepfun → OpenRouter) and the effective provider key is missing, frouter asks: Launch opencode anyway? (Y/n, default: n).

Configs written:

• OpenCode CLI → ~/.config/opencode/opencode.json
• OpenClaw → ~/.openclaw/openclaw.json

Existing configs are backed up before writing.

Settings screen (P)

Tip: press A from the main list to jump directly into API key editing.

Flags

--best scripted usage

# Print best model ID after ~10 s analysis
frouter --best

# Capture in a variable
MODEL=$(frouter --best)
echo "Best model: $MODEL"

Requires at least one API key to be configured. Selection tri-key sort: status=up → lowest avg latency → highest uptime.

Config

Stored at ~/.frouter.json (permissions 0600).

{
  "apiKeys": {
    "nvidia": "nvapi-xxx",
    "openrouter": "sk-or-xxx"
  },
  "providers": {
    "nvidia": { "enabled": true },
    "openrouter": { "enabled": true }
  }
}

Tier scale (SWE-bench Verified)

Verdict legend

Test

npm run lint
npm test
npm run typecheck

# optional perf workflow
npm run perf:baseline
npm run test:perf

Model catalog auto-sync (GitHub Actions)

frouter includes a scheduled workflow to keep model metadata current:

• Workflow: .github/workflows/model-catalog-sync.yml
• Triggers:
  • Daily: 17 3 * * * (UTC)
  • Weekly AA refresh: 47 4 * * 1 (UTC)
  • Manual: workflow_dispatch
• Updates:
  • model-rankings.json
  • model-support.json (OpenCode support map)
• If changes exist, it opens/updates a PR on chore/model-catalog-sync.
• If unresolved new-model tiers remain, PR gets needs-tier-review.

Repository secrets used by this workflow:

• NVIDIA_API_KEY
• OPENROUTER_API_KEY
• ARTIFICIAL_ANALYSIS_API_KEY

Local sync commands:

npm run models:sync
npm run models:sync:apply

Development notes

• TypeScript source of truth: src/ (app + tests)
• ESLint config is TypeScript: eslint.config.ts
• Runtime JS output is generated only in dist/ via npm run build
• Tests run from compiled dist/tests/ output after build