pp-openrouter

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/ai/openrouter/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# OpenRouter — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `openrouter-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install openrouter --cli-only
   ```
2. Verify: `openrouter-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/ai/openrouter/cmd/openrouter-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when an AI agent needs OpenRouter introspection data and you're optimizing for token efficiency. Absorbed commands accept `--agent` for compact JSON; the 8 novel commands ship `--llm` mode for terse key:value output. Use it when you need cost attribution beyond model+provider (which-cron-fired-the-call). Use it for pre-flight gates in bash compositions and for local-catalog querying that would otherwise blow context. Skip it for chat — use `grahamking/ort` for chat ergonomics.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`usage cost-by`** — Group your OpenRouter spend by which cron/agent fired the call, not just by model. Joins local generations with caller tags from your tool-call logger.

  _Use this when an agent needs to answer 'which automated job is burning my OpenRouter budget?' before deciding what to throttle._

  ```bash
  openrouter usage cost-by --group cron --since 7d --llm
  ```
- **`models query`** — Query the model catalog with structured filters (tools=true, cost.completion<1, ctx>=64k) — compiled to SQL over a local SQLite cache. Works offline.

  _Use this when an agent needs to shortlist models for an experiment without hallucinating pricing or pasting 400 model rows into context._

  ```bash
  openrouter models query "tools=true cost.completion<1 ctx>=64k modality=text" --llm
  ```
- **`generation explain`** — For a generation id, returns the cost, latency, prompt/completion token counts, AND a delta vs the cheapest provider for the same model+token-count.

  _Use this when an agent needs to decide whether a generation was expensive because of the model choice, the prompt size, or the provider markup._

  ```bash
  openrouter generation explain gen-abc123 --llm
  ```

### Agent-native plumbing
- **`providers degraded`** — Returns the set of currently-degraded provider/model pairs by polling /providers and per-model /endpoints. Pipe into your router to preempt 429s.

  _Use this in a router or fallback chain when an agent needs to skip degraded provider/model pairs before dispatch instead of after a failed call._

  ```bash
  openrouter providers degraded --json | jq -r '.[].model_id'
  ```
- **`usage anomaly`** — Flags days where per-model cost exceeds 2σ of the trailing 7-day mean. Deterministic z-score, no LLM in the loop. Designed for cron.

  _Use this in a daily cron when an agent needs to detect cost regressions before a credit-low alarm fires._

  ```bash
  openrouter usage anomaly --since 24h --baseline 7d --llm
  ```
- **`key eta`** — Projects when your weekly OpenRouter cap will trip, based on /key.limit_reset, current usage, and your trailing 7-day burn rate.

  _Use this in a daily cron when an agent needs to know whether scheduled work will fit in the remaining weekly cap._

  ```bash
  openrouter key eta --llm
  ```
- **`budget`** — Set a weekly USD cap per cron job (budget set scan-pipeline 2usd). Pre-flight check returns exit 0 (under cap) or 8 (over) from tagged generations.

  _Use this when an agent needs structural budget enforcement per sub-agent or per cron, not aspirational env-var quotas._

  ```bash
  openrouter budget check scan-pipeline && ./scan-pipeline.mjs
  ```
- **`endpoints failover`** — For a model id, lists all providers serving it ranked by current status, pricing, and observed p50 latency from local cache. Pipe-feeds routers.

  _Use this when an agent needs to choose a provider for a given model based on current availability, not the static config order._

  ```bash
  openrouter endpoints failover anthropic/claude-opus-4-7 --json
  ```

## Command Reference

**activity** — Manage activity

- `openrouter-pp-cli activity` — Returns user activity data grouped by endpoint for the last 30 (completed) UTC days. [Management...

**credits** — Credit management endpoints

- `openrouter-pp-cli credits` — Get total credits purchased and used for the authenticated user. [Management...

**endpoints** — Endpoint information

- `openrouter-pp-cli endpoints` — Preview the impact of ZDR on the available endpoints

**generation** — Generation history endpoints

- `openrouter-pp-cli generation get` — Get request & usage metadata for a generation
- `openrouter-pp-cli generation list-content` — Get stored prompt and completion content for a generation

**key** — Manage key

- `openrouter-pp-cli key` — Get information on the API key associated with the current authentication session

**keys** — Manage keys

- `openrouter-pp-cli keys create` — Create a new API key for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys)...
- `openrouter-pp-cli keys delete` — Delete an existing API key. [Management key](/docs/guides/overview/auth/management-api-keys) required.
- `openrouter-pp-cli keys get` — Get a single API key by hash. [Management key](/docs/guides/overview/auth/management-api-keys) required.
- `openrouter-pp-cli keys list` — List all API keys for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.
- `openrouter-pp-cli keys update` — Update an existing API key. [Management key](/docs/guides/overview/auth/management-api-keys) required.

**models** — Model information endpoints

- `openrouter-pp-cli models get` — List all models and their properties
- `openrouter-pp-cli models list-count` — Get total count of available models
- `openrouter-pp-cli models list-user` — List models filtered by user provider preferences, [privacy settings](https://openrouter.ai/docs/guides/privacy/provi...

**openrouter-auth** — Manage openrouter auth

- `openrouter-pp-cli openrouter-auth create-keys-code` — Create an authorization code for the PKCE flow to generate a user-controlled API key
- `openrouter-pp-cli openrouter-auth exchange-code-for-apikey` — Exchange an authorization code from the PKCE flow for a user-controlled API key

**providers** — Provider information endpoints

- `openrouter-pp-cli providers` — List all providers


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
openrouter-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Pre-flight gate before expensive cron

```bash
openrouter