openrouter-cli

openrouter-cli is a workspace CLI companion for openrouter-rs.

Current Scope

• OR-19: command bootstrap and config/profile resolution
• OR-20: discovery commands for models/providers/endpoints
• OR-21: management commands for API keys and guardrails
• OR-22: usage and billing commands with stable output contracts

Installation

Install from crates.io:

cargo install openrouter-cli

Install from local source:

cargo install --path crates/openrouter-cli

Install prebuilt binaries from GitHub Releases:

VERSION=0.1.0
curl -L -o openrouter-cli.tar.gz \
  "https://github.com/realmorrisliu/openrouter-rs/releases/download/openrouter-cli-v${VERSION}/openrouter-cli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"
curl -L -o SHA256SUMS \
  "https://github.com/realmorrisliu/openrouter-rs/releases/download/openrouter-cli-v${VERSION}/SHA256SUMS"
grep "openrouter-cli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz" SHA256SUMS | sha256sum -c -
tar -xzf openrouter-cli.tar.gz
./openrouter-cli --help

For macOS and Windows, use the matching target archive from the same release tag.

Config And Profile Convention

By default, config is loaded from:

• $XDG_CONFIG_HOME/openrouter/profiles.toml, or
• $HOME/.config/openrouter/profiles.toml

You can override with:

• --config <path>
• OPENROUTER_CLI_CONFIG

Config format:

default_profile = "default"

[profiles.default]
api_key = "sk-or-v1-..."
management_key = "or-mgmt-..."
base_url = "https://openrouter.ai/api/v1"

Resolution Priority

For api_key, management_key, and base_url:

1. CLI flags (--api-key, --management-key, --base-url)
2. Environment (OPENROUTER_API_KEY, OPENROUTER_MANAGEMENT_KEY, OPENROUTER_BASE_URL)
3. Active profile values from config file
4. Defaults (for base_url: https://openrouter.ai/api/v1)

For profile selection:

1. --profile
2. OPENROUTER_PROFILE
3. default_profile in config
4. "default"

Discovery Commands (OR-20)

openrouter-cli now supports discovery workflows:

• models list with optional filters:
  • --category
  • --supported-parameter
• models show <model_id>
• models endpoints <model_id>
• providers list

Examples:

# List models in a category
openrouter-cli --api-key "$OPENROUTER_API_KEY" models list --category programming

# List models supporting tool-calling parameter
openrouter-cli --api-key "$OPENROUTER_API_KEY" models list --supported-parameter tools

# Show one model
openrouter-cli --api-key "$OPENROUTER_API_KEY" models show openai/gpt-4.1

# Show endpoints for one model
openrouter-cli --api-key "$OPENROUTER_API_KEY" models endpoints openai/gpt-4.1

# List providers
openrouter-cli --api-key "$OPENROUTER_API_KEY" providers list

Management Commands (OR-21)

openrouter-cli supports management workflows:

• keys list|create|get|update|delete
• guardrails list|create|get|update|delete
• guardrails assignments keys list|assign|unassign
• guardrails assignments members list|assign|unassign

Examples:

# List keys
openrouter-cli --management-key "$OPENROUTER_MANAGEMENT_KEY" keys list --include-disabled

# Create and update key
openrouter-cli --management-key "$OPENROUTER_MANAGEMENT_KEY" keys create --name "ci-bot" --limit 100
openrouter-cli --management-key "$OPENROUTER_MANAGEMENT_KEY" keys update sk-or-v1-hash --disable

# Delete key (requires explicit confirmation)
openrouter-cli --management-key "$OPENROUTER_MANAGEMENT_KEY" keys delete sk-or-v1-hash --yes

# Update guardrail and clear allowlists
openrouter-cli --management-key "$OPENROUTER_MANAGEMENT_KEY" guardrails update gr_123 --clear-allowed-providers --clear-allowed-models

Usage And Billing Commands (OR-22)

Supported command groups:

• credits show
• credits charge --amount --sender --chain-id
• usage activity [--date YYYY-MM-DD]

Examples:

# Show total credits and usage
openrouter-cli --api-key "$OPENROUTER_API_KEY" credits show

# Create Coinbase charge
openrouter-cli \
  --api-key "$OPENROUTER_API_KEY" \
  credits charge \
  --amount 25 \
  --sender 0xYourWalletAddress \
  --chain-id 1

# Query usage activity for a specific day (requires management key)
openrouter-cli \
  --management-key "$OPENROUTER_MANAGEMENT_KEY" \
  usage activity \
  --date 2026-02-28

Output Contract

--output supports:

• table (default)
• json

JSON output is wrapped with schema metadata for automation stability:

{
  "schema_version": "0.1",
  "data": { "...": "..." }
}

Error output in JSON mode follows:

{
  "schema_version": "0.1",
  "error": {
    "code": "cli_error",
    "message": "..."
  }
}

CLI Live Smoke Tests

This repo includes an opt-in CLI live smoke suite (tests/live_smoke.rs) for real API verification.

Environment switches:

• OPENROUTER_CLI_RUN_LIVE=1: enable live tests.
• OPENROUTER_CLI_RUN_LIVE_WRITE=1: also enable write-path lifecycle checks (create/delete keys and guardrails).

Required secrets:

• OPENROUTER_API_KEY (read smoke)
• OPENROUTER_MANAGEMENT_KEY (usage activity and write smoke)

Local examples:

# Read-only live smoke
OPENROUTER_CLI_RUN_LIVE=1 \
OPENROUTER_API_KEY=... \
cargo test -p openrouter-cli --test live_smoke -- --nocapture --test-threads=1

# Include write lifecycle smoke
OPENROUTER_CLI_RUN_LIVE=1 \
OPENROUTER_CLI_RUN_LIVE_WRITE=1 \
OPENROUTER_API_KEY=... \
OPENROUTER_MANAGEMENT_KEY=... \
cargo test -p openrouter-cli --test live_smoke -- --nocapture --test-threads=1