ORCLI — OpenRouter CLI

A full-featured AI coding assistant CLI powered by OpenRouter.ai. Designed as a Copilot CLI replacement with OpenRouter-exclusive capabilities: 400+ models, per-session cost tracking, streaming markdown rendering, model comparison, provider routing, and more.

Features

Core

Streaming markdown rendering — headings, bold/italic, code blocks, lists, blockquotes rendered live as the AI types
400+ models via OpenRouter — switch models mid-session with /model
Persistent sessions — SQLite-backed with full history, cost, and tags; auto-saves every 2 minutes
Non-interactive mode — -p flag with text, json, or jsonl (JSONL streams each tool event in real time)
Tool use — 20+ AI-callable tools including file I/O, shell, web search/browse, git, GitHub, clipboard, and more
Permission system — allow/deny rules per tool, path, and URL; interactive approval prompts; persist-to-config

OpenRouter-Exclusive

Per-session cost tracking — every response accumulates cost; /usage shows token and cost totals
/cost-history — all-time spend across all sessions, top 10 most expensive sessions
/balance — live OpenRouter account balance, credit limit, and rate-limit info
/compare [model] — sends the last user message to a second model for side-by-side comparison
--prefer-free — routes to the free tier of the current model
--optimize speed|cost|quality — maps to OpenRouter provider sort (latency/price/throughput)
Reasoning controls — --effort / --reasoning-effort: xhigh, high, medium, low, minimal, none
Provider routing — per-request provider order, only, ignore, sort, require_parameters, data_collection, zdr
Model fallback chains — --fallback-model passes a priority list to OpenRouter's models array
Pareto Router plugin — min_coding_score and variant parameters for intelligent routing
Model discovery — /models, /providers, /recommend-model with filters and table rendering

Session & Workflow

Session tagging — /tag, /tag remove, /tag clear; tags shown in session list
/plan run — reads numbered steps from plan.md and executes each via the normal chat loop
/retry — re-runs the last user message
/doctor — environment diagnostics (API key, connectivity, git, gh, npm, Node.js)
Context-window warning — warns at 75% / 90% of the active model's context limit
Auto-save — background 2-minute interval; all exit paths (Ctrl+C, Ctrl+D, /exit) also save

Terminal UI

Compact ORCLI banner; boxed You › input with footer hints
Streamed AI responses under AI › prefix with real-time markdown formatting
Concise tool progress: Tool: running X / Tool: X done (Yms, Z KB) with end-of-turn summary
Per-turn cost/token line after every response: ↑ Xk · ↓ Y · $0.000NNN
Queue follow-up prompts while AI is busy; Esc clears queue or cancels; Ctrl+C cancels + clears

VS Code Extension

OR-CLI is also available as a VS Code extension (orcli-vscode). The CLI and VS Code extension are developed and released together, so their version numbers match. Install the .vsix from the releases page or build it yourself:

cd vscode-extension
npm install
npm run build
npm run package
code --install-extension orcli-vscode-*.vsix

The extension provides a persistent sidebar chat panel, streaming markdown rendering, workspace-aware tools (read file, apply edits with diff preview, run tasks, search workspace), session management, MCP server support, manual model ID entry, and a @orcli participant in VS Code's built-in chat. Use OR-CLI: Change Model, sidebar /model <model-id>, or the settings panel model field to enter an exact OpenRouter model ID when it is not in the browser list. See vscode-extension/README.md for full documentation.

Installation

Prerequisites

Node.js v18+ with npm — nodejs.org
git — git-scm.com
OpenRouter API key — openrouter.ai/keys

One-line install

Windows (PowerShell):

irm https://swatto.co.uk/tools/orcli/install.ps1 | iex

Linux / macOS:

curl -fsSL https://swatto.co.uk/tools/orcli/install.sh | bash

The installer clones https://github.com/Swatto86/openrouter-cli.git, builds the CLI, creates the orcli launcher, and adds it to your PATH. Re-run the same command to update.

GitHub raw fallback (if above URLs are unavailable):

irm https://raw.githubusercontent.com/Swatto86/openrouter-cli/master/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/Swatto86/openrouter-cli/master/install.sh | bash

After install, run orcli --setup to configure your API key. If orcli is not found immediately, restart your terminal.

ORCLI checks for updates on startup. When an update is available, the prompt footer shows Update available: /update — run /update to switch to the updater, pull the latest changes, and relaunch ORCLI in the same terminal.

Install from source

git clone https://github.com/Swatto86/openrouter-cli.git
cd openrouter-cli
npm install
npm run build
npm link

Configuration

API key

Environment variable (recommended):

# Linux/macOS
export OPENROUTER_API_KEY="sk-or-v1-..."

# Windows PowerShell
$env:OPENROUTER_API_KEY="sk-or-v1-..."

Add to your shell profile (~/.bashrc, ~/.zshrc, or $PROFILE) for persistence.

Environment variables

Variable	Default	Description
`OPENROUTER_API_KEY`	—	Required. Your OpenRouter API key.
`ORCLI_LOG_LEVEL`	`info`	Log verbosity: `debug\|info\|warn\|error\|silent`
`ORCLI_API_TIMEOUT_MS`	`180000`	OpenRouter request timeout in ms
`ORCLI_API_MAX_RETRIES`	`3`	Retries for transient OpenRouter errors (`429`, `5xx`, network failures)
`ORCLI_API_MAX_RETRY_DELAY_MS`	`120000`	Maximum retry sleep after exponential backoff or OpenRouter retry headers
`ORCLI_TOOL_TIMEOUT_MS`	`120000`	Per-tool execution timeout in ms
`ORCLI_STALL_TIMEOUT_MS`	`120000`	Idle watchdog timeout in ms; `0` disables

Config file

~/.openrouter/config.json — created by orcli --setup:

{
  "defaultModel": "openrouter/pareto-code",
  "modelFallbacks": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o"
  ],
  "plugins": [
    {
      "id": "pareto-router",
      "min_coding_score": 0.8,
      "variant": "default"
    }
  ],
  "params": {
    "temperature": 0.7,
    "reasoning": { "effort": "high" }
  },
  "provider": {
    "sort": "throughput",
    "require_parameters": true,
    "data_collection": "deny"
  }
}

Project-specific overrides go in .openrouterrc.json in your project directory.

Rate limit handling

ORCLI retries transient OpenRouter failures and uses Retry-After / rate-limit reset headers when OpenRouter returns them. If a session was pinned to one provider and that provider returns a transient error, ORCLI releases the pin for the retry so OpenRouter can route to another eligible provider.

Free models still have hard quotas and upstream provider throttles. Practical mitigations:

Run /balance to check the active key's current rate-limit info.
Configure modelFallbacks or pass --fallback-model with several acceptable model IDs.
Leave provider fallbacks enabled; avoid --provider-only unless you need it.
For free-heavy sessions, set "providerPinning": false in config if cache consistency matters less than avoiding a throttled provider.

Usage

Interactive REPL

orcli
orcli --interactive
openrouter-cli

With session control:

orcli --continue                          # resume most recent session
orcli --resume                            # pick from interactive session list
orcli --resume session-2026-05-11T12-...  # resume by ID
orcli --name feature-work                 # start a new named session

One-shot subcommands (no REPL)

orcli explain "tar -xzf archive.tar.gz"   # explain a shell command
orcli suggest "list files by size"         # get a shell command for a task
orcli suggest "backup my home dir" --shell powershell --explain
orcli completion bash >> ~/.bashrc         # install tab completion
orcli completion zsh
orcli completion fish
orcli completion powershell

Non-interactive prompt mode

orcli -p "Summarize the architecture of this repo"
orcli -p "Generate a changelog" -s                     # silent: AI text only
orcli -p "Return JSON release notes" --output-format json
orcli -p "Stream tool events to CI" --output-format jsonl
orcli -p "Review this code" --show-tool-calls
orcli -p "Audit this repo" --max-tool-rounds 20
orcli -p "Summarize this repo" --share ./session.md    # export to Markdown
orcli -p "Create a gist" --share-gist                  # upload to GitHub Gist

CLI Flags

Model & reasoning

Flag	Description
`--model <model>`	Model ID to use (e.g. `anthropic/claude-3.5-sonnet`)
`--fallback-model <models>`	Fallback model IDs, repeatable or comma-separated
`--effort <level>`	Reasoning effort: `xhigh\|high\|medium\|low\|minimal\|none`
`--reasoning-effort <level>`	Alias for `--effort`
`--prefer-free`	Append `:free` to the model ID for free-tier routing
`--optimize <mode>`	Provider sort: `speed` (latency) · `cost` (price) · `quality` (throughput)

OpenRouter provider routing

Flag	Description
`--provider-order <providers>`	Comma-separated provider slugs, tried in order
`--provider-only <providers>`	Restrict routing to these provider slugs
`--provider-ignore <providers>`	Skip these provider slugs
`--provider-sort <sort>`	`price\|throughput\|latency`
`--no-provider-fallbacks`	Disable provider fallbacks
`--require-parameters`	Only route to providers supporting all parameters
`--data-collection <policy>`	`allow\|deny`
`--zdr`	Require Zero Data Retention endpoints

Pareto Router plugin

Flag	Description
`--min-coding-score <score>`	Filter models by coding score (0–1)
`--variant <variant>`	`default` or `nitro`

Session (REPL only)

Flag	Description
`--continue`	Resume the most recent session
`--resume [sessionId]`	Resume a session; omit ID for interactive picker
`--name <name>`	Start a new named session

Output & prompt mode

Flag	Description
`-p, --prompt <text>`	Run a single non-interactive prompt
`-s, --silent`	Print AI text only (no metadata)
`--output-format <fmt>`	`text` (default) · `json` · `jsonl`
`--stream <mode>`	`auto` (default) · `on` · `off`
`--share [path]`	Export prompt session to Markdown
`--share-gist`	Upload prompt session to a GitHub Gist

Automation & safety

Flag	Description
`--show-tool-calls`	Show full tool-call progress logs
`--max-tool-rounds <n>`	Cap tool-call rounds per response (`unlimited` for no cap)
`--max-autopilot-continues <n>`	Cap `/agent` autonomous steps (default: 15)
`--stall-timeout <seconds>`	Cancel after N seconds of inactivity; `0` disables
`--no-ask-user`	Disable the `ask_user` tool
`--secret-env-vars <vars>`	Redact env var values from tool and AI output
`--approval-mode <mode>`	`auto` (default) · `prompt` (interactive approval, REPL only)
`--log-level <level>`	`debug\|info\|warn\|error\|silent` (env: `ORCLI_LOG_LEVEL`)
`--no-telemetry`	Accepted for scripting compatibility (ORCLI collects no telemetry)

Permission rules

Flag	Description
`--allow-all`	Allow all tools and path access
`--allow-all-tools`	Allow all tools
`--allow-all-paths`	Allow file access outside the working directory
`--allow-all-urls`	Allow all URL access
`--allow-tool <rule>`	Allow tool rule, repeatable or comma-separated
`--deny-tool <rule>`	Deny tool rule, repeatable or comma-separated
`--allow-url <pattern>`	Allow URL pattern
`--deny-url <pattern>`	Deny URL pattern
`--add-dir <path>`	Add an allowed directory for file operations

Rule examples: read, write(src/*), shell(git*), execute_shell_command, https://api.duckduckgo.com

Terminal display

Flag	Description
`--banner` / `--no-banner`	Show or hide startup banner
`--no-color`	Disable color output
`--screen-reader`	Enable screen reader optimized output
`--no-custom-instructions`	Disable loading AGENTS.md and Copilot instruction files

REPL Commands

Navigation & display

Command	Description
`/help [topic]`	List commands or show a detailed help topic
`/model [id]`	List available models or set the active model
`/models [query]`	Browse OpenRouter models with filters
`/providers [query]`	Browse OpenRouter providers
`/recommend-model [query]`	Rank models for a task
`/params`	Show current sampling parameters
`/params set <key> <value>`	Set a sampling parameter
`/env`	Show environment info and active permission summary
`/context`	Show token usage vs. model context limit
`/usage`	Show session token and cost totals
`/cost-history`	All-time cost summary across all sessions
`/balance`	Live OpenRouter account balance and credit info
`/doctor`	Environment diagnostics (API key, connectivity, tools)

Conversation management

Command	Description
`/clear`	Clear conversation history
`/history`	Show conversation history
`/compact`	Compress history (keeps last 10 messages)
`/rewind N`	Remove last N message pairs
`/retry`	Re-run the last user message
`/cancel`	Cancel the current streaming response

Session management

Command	Description
`/session`	List all saved sessions (with cost, message count, tags)
`/session delete <id>`	Permanently delete a session
`/resume <id>`	Load a session by ID
`/rename <name>`	Rename the current session
`/search <query>`	Full-text search across all saved sessions
`/tag <tag>`	Add a tag to the current session
`/tag remove <tag>`	Remove a tag
`/tag clear`	Clear all tags
`/share`	Export the current session to Markdown
`/share-gist`	Upload the current session to a GitHub Gist

AI tasks

Command	Description
`/ask <question>`	Quick one-shot question (not saved to session history)
`/agent <task>`	Run a multi-step autonomous task
`/compare [model]`	Compare the last response with another model
`/review`	AI code review of the current git diff
`/research [topic]`	AI-assisted research with web search
`/diff`	Show the current git diff

Plans & workflow

Command	Description
`/plan [query]`	Generate a structured plan for a task
`/plan run`	Execute steps from `plan.md` (CWD) or `~/.openrouter/current-plan.md`

GitHub

Command	Description
`/repos`	List your GitHub repositories
`/prs [repo]`	List pull requests
`/issues [repo]`	List issues

Configuration & plugins

Command	Description
`/plugins`	Show active plugins
`/plugin set min_coding_score <0-1>`	Set Pareto Router coding score
`/plugin set variant <default\|nitro>`	Set Pareto Router variant
`/init`	Create an AGENTS.md instruction template
`/streamer-mode`	Toggle reduced metadata output
`/update`	Update git-backed ORCLI and relaunch in the same terminal
`/exit`, `/quit`	Exit the CLI

Help topics (use /help <topic>): commands, config, environment, logging, monitoring, permissions, providers, automation

Input Syntax

@filename — attach a file to your message
!command — run a shell command inline
Ctrl+G — open the current prompt in $EDITOR (or notepad on Windows)
Ctrl+S — submit the current input while keeping it visible for reuse

While AI is busy:

Type + Enter / Ctrl+Q — queue a follow-up prompt
Esc — clear queued prompts (or cancel if none queued)
Ctrl+C — cancel current operation and clear queue

Cost Tracking

Every API response accumulates token and cost data. After each response:

↑ 2.1k  ·  ↓ 847  ·  $0.00042

(prompt tokens · completion tokens · turn cost)

Session totals:

/usage          → tokens + cost for this session
/cost-history   → all-time spend, top 10 sessions by cost
/balance        → live account balance on OpenRouter

Session Tags

Annotate sessions for easy filtering:

/tag refactor
/tag remove refactor
/tag clear

Tags appear in the /session list table.

Permission System

ORCLI gates every tool call. By default all tools need approval unless rules say otherwise.

orcli --allow-all                         # no restrictions
orcli --allow-tool read --allow-tool write(src/*)
orcli --deny-tool execute_shell_command
orcli --allow-url https://api.github.com --deny-url '*internal*'
orcli --approval-mode prompt              # ask interactively for each tool

In interactive mode, the approval prompt offers:

[y] allow once
[s] allow for this session
[p] persist to ~/.openrouter/config.json
[n] deny

Custom Instructions

ORCLI loads these files automatically (disable with --no-custom-instructions):

~/.copilot/copilot-instructions.md
AGENTS.md
.github/copilot-instructions.md
.github/instructions.md
.github/instructions/**/*.instructions.md
CLAUDE.md

Files with excludeAgent: true front matter are skipped.

OpenRouter Model Discovery

/models claude --tools --reasoning
/models gemini --image --limit 10
/providers openai
/recommend-model --task coding --tools --reasoning
/recommend-model --task cheap --max-prompt-price 1 --limit 5

The AI can also call openrouter_list_models, openrouter_list_providers, and openrouter_recommend_models as tools during a session.

Sampling Parameters

/params set temperature 0.5
/params set top_p 0.9
/params set seed 42

Parameter	Range	Description
`temperature`	0–2	Output randomness
`top_p`	0–1	Nucleus sampling
`top_k`	0+	Top-k sampling
`frequency_penalty`	−2 to 2	Penalize repeated tokens
`presence_penalty`	−2 to 2	Penalize new topics
`repetition_penalty`	0–2	Repetition penalty
`min_p`	0–1	Minimum probability
`top_a`	0–1	Top-a sampling
`seed`	integer	Reproducible output
`reasoning.effort`	xhigh/high/medium/low/minimal/none	Reasoning budget

Programmatic JSONL Output

--output-format jsonl streams each event as newline-delimited JSON:

{"type":"tool_call_start","callId":"call_...","name":"read_file","args":{"path":"src/index.ts"},"timestamp":"..."}
{"type":"tool_call_end","callId":"call_...","name":"read_file","resultLength":4096,"durationMs":12,"timestamp":"..."}
{"schema_version":"orcli.prompt.v2","stream":"on","content":"...","model":"...","usage":{"cost":0.00042}}

The final JSON envelope also includes a full events array for non-streaming consumers (--output-format json).

Development

npm install
npm run build   # compile TypeScript
npm run lint    # ESLint
npm run dev     # watch mode
npm --prefix vscode-extension run typecheck
npm --prefix vscode-extension run build
npm --prefix vscode-extension run package

Architecture overview: docs/ARCHITECTURE.md

Copilot parity tracking: docs/COPILOT_REPLACEMENT_SCORECARD.md

Feature progress: docs/FEATURES_PROGRESS.md

License

MIT — see LICENSE

Acknowledgments

Inspired by GitHub Copilot CLI
Powered by OpenRouter.ai

Name		Name	Last commit message	Last commit date
Latest commit History 130 Commits
.github/workflows		.github/workflows
src		src
vscode-extension		vscode-extension
.eslintignore		.eslintignore
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

ORCLI — OpenRouter CLI

Features

Core

OpenRouter-Exclusive

Session & Workflow

Terminal UI

VS Code Extension

Installation

Prerequisites

One-line install

Install from source

Configuration

API key

Environment variables

Config file

Rate limit handling

Usage

Interactive REPL

One-shot subcommands (no REPL)

Non-interactive prompt mode

CLI Flags

Model & reasoning

OpenRouter provider routing

Pareto Router plugin

Session (REPL only)

Output & prompt mode

Automation & safety

Permission rules

Terminal display

REPL Commands

Navigation & display

Conversation management

Session management

AI tasks

Plans & workflow

GitHub

Configuration & plugins

Input Syntax

Cost Tracking

Session Tags

Permission System

Custom Instructions

OpenRouter Model Discovery

Sampling Parameters

Programmatic JSONL Output

Development

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages