OpenRouter CLI: Ori, curl, llm e aichat

Cercando una OpenRouter CLI si finisce davanti a due risposte diverse. Il comando ufficiale ori di OpenRouter configura e avvia agent di coding già esistenti, mentre i client della community offrono prompt singoli, chat REPL, output JSON o una copertura più ampia delle API. Se ti serve soltanto una pipeline da shell, bastano l’API di OpenRouter e curl.

Cosa significa davvero “OpenRouter CLI”

“OpenRouter CLI” non è il nome di un unico client ufficiale universale da terminale. L’espressione indica tre workflow distinti: avviare un agent tramite OpenRouter, chiamare direttamente l’API dalla shell oppure usare un workbench di terze parti come llm o aichat.

La distinzione fondamentale riguarda titolarità e ambito. L’integrazione ori di OpenRouter e il pacchetto DevTools @openrouter/cli sono ufficiali, ma nessuno dei due è un client generico del tipo openrouter ask: il pacchetto DevTools si concentra su un visualizzatore della telemetria SDK e su una status line per Claude Code, mentre Ori avvia harness già esistenti.

Il percorso ufficiale: installare e usare Ori Harness

Ori è la CLI ufficiale di OpenRouter per configurare gli harness di coding supportati. Esegue l’autenticazione con OpenRouter, passa il modello selezionato all’agent sottostante e mantiene disponibili i comandi e i flag abituali di quell’agent; non sostituisce Claude Code, Codex, OpenCode o gli altri harness.

Installalo con il comando indicato nell’annuncio e nella guida di OpenRouter:

curl -fsSL https://openrouter.ai/labs/ori/install.sh | bash

Poi effettua l’autenticazione e avvia un agent:

ori login
ori claude
ori codex
ori opencode
ori hermes

La documentazione attuale di Ori include tra i comandi supportati anche grok, pi, prime-agent e dsh. ori dsh configura DeepSeek Harness ma non lo avvia: dopo bisogna eseguire dsh. Per aggiornare Ori puoi usare ori update.

Scegliere il modello senza cambiare agent

Ori accetta un ID modello di OpenRouter e inoltra gli argomenti non riconosciuti all’harness sottostante:

ori claude --model anthropic/claude-sonnet-4.6
ori codex --model openai/gpt-5.2 --full-auto
ori opencode --model openrouter/auto
ori hermes --model openrouter/auto

I dettagli degli endpoint non sono identici per tutti gli agent. Per esempio, le indicazioni di OpenRouter per Claude Code usano il base URL compatibile con Anthropic https://openrouter.ai/api, mentre i client compatibili con OpenAI come Codex usano https://openrouter.ai/api/v1; Ori serve anche a nascondere queste differenze di configurazione tra i vari harness.

Ori usa OAuth PKCE basato sul browser, quindi il percorso normale non richiede di incollare una chiave API di OpenRouter in ogni agent. La documentazione di Ori Harness di OpenRouter specifica che le richieste seguono la normale fatturazione e la normale reportistica delle attività di OpenRouter, senza un conto Ori separato; il modello selezionato e l’harness sottostante continuano comunque a determinare il costo dell’inferenza.

Ori non è una chat REPL autonoma

Usa Ori quando ti servono già gli strumenti di un agent, le operazioni sui file o il suo modello di approvazione. Scegli curl, un client diretto, llm o aichat quando devi inviare un prompt, ottenere una risposta strutturata o creare una pipeline da shell senza avviare un agent di coding.

Il confine è importante perché il materiale ufficiale di lancio presenta Ori come un livello di compatibilità e configurazione. Anche il pacchetto ufficiale @openrouter/cli può generare confusione: i comandi documentati attualmente sono openrouter devtools e openrouter statusline, mentre la linea 1.0 ha rimosso i precedenti comandi proxy come start, stop, restart e code.

I client OpenRouter della community da conoscere

I client della community si differenziano soprattutto per l’interfaccia da terminale che mettono a disposizione. La scelta pratica dipende dal fatto che servano un selettore interattivo, una copertura completa delle API, un binario leggero, automazioni multi-modello oppure un output prevedibile e leggibile dalle macchine.

Si tratta di funzionalità documentate, non di benchmark comparativi sulle prestazioni.

Il workflow più essenziale e affidabile: curl e jq

Se curl e jq sono già installati, l’API OpenRouter usata direttamente è il percorso da terminale più piccolo e trasparente. La Quickstart di OpenRouter documenta l’autenticazione Bearer, l’endpoint compatibile con OpenAI /api/v1/chat/completions, il campo model, l’array messages e lo streaming opzionale.

Imposta una chiave e un modello nella sessione shell:

export OPENROUTER_API_KEY='sk-or-v1-...'
export OR_MODEL='openai/gpt-4o'

Poi invia un prompt:

curl -sS https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg model "$OR_MODEL" \
    --arg prompt "Explain Unix pipes in three sentences." \
    '{model: $model, messages: [{role: "user", content: $prompt}], stream: false}')" \
  | jq -r '.choices[0].message.content // .error.message'

Usa una variabile d’ambiente per il modello invece di copiare un ID in ogni script. L’API ufficiale Models espone id, lunghezza del contesto, prezzi, parametri supportati, limiti del provider e metadati opzionali dei benchmark.

Racchiudere la richiesta in funzioni shell riutilizzabili

Queste funzioni mantengono il corpo della richiesta sicuro per il formato JSON, lasciando a jq il compito di codificare il prompt. orask serve per un argomento; orpipe legge tutto lo standard input come un unico prompt.

orask() {
  local prompt="$*"
  local model="${OR_MODEL:?Set OR_MODEL to an OpenRouter model ID}"

  jq -n \
    --arg model "$model" \
    --arg prompt "$prompt" \
    '{model: $model, messages: [{role: "user", content: $prompt}], stream: false}' \
  | curl -sS --fail-with-body \
      https://openrouter.ai/api/v1/chat/completions \
      -H "Authorization: Bearer ${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq -r '.choices[0].message.content // .error.message // "Unknown OpenRouter error"'
}

orpipe() {
  orask "$(cat)"
}

Esempi:

orask "Turn this error message into a likely diagnosis: connection reset by peer"
cat README.md | orpipe

Per gli script che hanno bisogno dei metadati, conserva il JSON invece di estrarre soltanto il testo:

orjson() {
  local prompt="$*"
  local model="${OR_MODEL:?Set OR_MODEL to an OpenRouter model ID}"

  jq -n \
    --arg model "$model" \
    --arg prompt "$prompt" \
    '{model: $model, messages: [{role: "user", content: $prompt}], stream: false}' \
  | curl -sS --fail-with-body \
      https://openrouter.ai/api/v1/chat/completions \
      -H "Authorization: Bearer ${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @-
}

In questo modo l’oggetto usage della risposta resta disponibile per il calcolo dei costi e gli errori API possono essere distinti da una risposta del modello priva di contenuto.

Individuare dalla riga di comando i modelli compatibili

La presenza di un modello nel catalogo non implica che supporti ogni parametro di richiesta. Le Models API di OpenRouter permettono di filtrare per supported_parameters, incluso tools, e di ordinare per prezzo, contesto, throughput, latenza, popolarità o recenza.

Elenca i modelli compatibili con gli strumenti partendo dall’estremità più economica dell’ordinamento documentato:

curl -sS -G https://openrouter.ai/api/v1/models \
  --data-urlencode 'supported_parameters=tools' \
  --data-urlencode 'sort=pricing-low-to-high' \
| jq -r '.data[] | [.id, .context_length, .pricing.prompt, .pricing.completion] | @tsv' \
| head -20

Controlla un modello prima di inserirlo in uno script di produzione. OpenRouter documenta il percorso per i dettagli del singolo modello come /api/v1/model/{author}/{slug}:

curl -sS \
  "https://openrouter.ai/api/v1/model/${OR_MODEL}" \
| jq '.data | {id, context_length, architecture, pricing, supported_parameters, top_provider}'

I valori di pricing sono espressi per token o unità: non leggere quindi un decimale grezzo come se fosse un prezzo in dollari per milione senza prima convertirlo. Il campo usage della risposta è la fonte più affidabile per sapere quanti token di input e output ha consumato effettivamente una richiesta.

Elaborazione batch in una pipeline shell

Un workflow batch utile consiste nell’avere un prompt per riga in un file di testo e un oggetto JSON per ogni risultato. Lo script seguente registra prompt originale, risposta, utilizzo e un campo per gli errori, senza mescolare il testo prodotto dal modello con l’output leggibile dalle macchine.

Crea prompts.txt:

Summarize the release notes in one paragraph.
List three security risks in this configuration.
Extract the names and versions from this sentence.

Esegui il batch:

#!/usr/bin/env bash
set -u

: "${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY}"
: "${OR_MODEL:?Set OR_MODEL}"

while IFS= read -r prompt || [[ -n "$prompt" ]]; do
  [[ -z "$prompt" ]] && continue

  request=$(jq -n \
    --arg model "$OR_MODEL" \
    --arg prompt "$prompt" \
    '{model: $model, messages: [{role: "user", content: $prompt}], stream: false}')

  response=$(curl -sS --fail-with-body \
    https://openrouter.ai/api/v1/chat/completions \
    -H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "$request" || true)

  if jq -e '.choices[0].message.content' >/dev/null 2>&1 <<<"$response"; then
    jq -c --arg prompt "$prompt" \
      '{prompt: $prompt, answer: .choices[0].message.content, usage: (.usage // null)}' \
      <<<"$response"
  else
    jq -c --arg prompt "$prompt" \
      '{prompt: $prompt, answer: null, error: (.error.message // "Request failed"), usage: (.usage // null)}' \
      <<<"$response"
  fi
done < prompts.txt > results.jsonl

Lo script esegue le richieste in sequenza; aggiungi concorrenza solo dopo aver verificato limiti e budget, perché le richieste parallele possono far crescere rapidamente i costi. La pagina dei prezzi di OpenRouter indica 50 richieste al giorno per il piano gratuito e una commissione della piattaforma del 5.5% per il consumo a pagamento: quindi un modello gratuito non equivale a una capacità batch illimitata.

Dove si collocano llm e aichat

llm e aichat sono workbench generici da terminale che supportano OpenRouter. Hanno più senso di un piccolo wrapper quando servono prompt riutilizzabili, sessioni, allegati, strumenti, modelli locali o uno storico del lavoro svolto.

llm-openrouter: l’opzione con log ed estensioni

Installa prima il comando base llm, poi aggiungi il plugin OpenRouter:

llm install llm-openrouter
llm keys set openrouter

Il plugin documenta OPENROUTER_KEY come nome della variabile d’ambiente. Espone i modelli OpenRouter con nomi come openrouter/anthropic/claude-sonnet-5, conserva l’elenco dei modelli nella cache per un’ora e lo aggiorna con:

llm openrouter refresh
llm models list

Un prompt normale e una pipeline shell hanno questo aspetto:

llm -m openrouter/anthropic/claude-sonnet-5 \
  "Give me five short names for a pet tarantula"

cat app.py | llm -m openrouter/anthropic/claude-sonnet-5 \
  -s "Review this code for a security bug"

Il plugin documenta schemi, allegati, chiamate agli strumenti, opzioni di ragionamento, JSON per il routing dei provider, strumenti web di OpenRouter e ispezione delle chiavi. È una via di mezzo tra curl usato direttamente e un harness di coding autonomo, ma la sua cache dei modelli può rimanere indietro rispetto al catalogo aggiornato.

aichat: il workbench da terminale più ampio

aichat è una CLI basata su Rust che supporta OpenRouter insieme a oltre 20 provider nominativi ed endpoint compatibili con OpenAI. Le funzionalità documentate includono la modalità CMD, una Chat-REPL, assistenza per la shell, sessioni, macro, RAG, function calling, strumenti MCP, agent e un server locale con endpoint per chat, embeddings e reranking.

La configurazione OpenRouter usa un client compatibile con OpenAI che punta a https://openrouter.ai/api/v1, mentre gli esempi del progetto impiegano il formato modello openrouter:<model>. Sceglilo quando il terminale sta diventando l’interfaccia della tua applicazione; preferisci curl o llm quando vuoi un percorso di richiesta più piccolo e facile da ispezionare.

Risolvere gli errori che sembrano problemi della CLI

Gli errori della OpenRouter CLI possono nascere al confine tra shell, client, modello selezionato e account. Prima di cambiare strumento, analizza separatamente questi livelli.

In una discussione su Reddit riguardo a OpenCode e Kilo Code, l’utente u/GrevireDev ha scritto:

“Both Kilo Code and OpenCode maintain a hard-coded/preloaded list of OpenRouter models instead of dynamically fetching the full catalog.” — r/openrouter

L’utente u/DrunkenRobotBipBop ha fatto questa osservazione su costi e cache in un’altra discussione su OpenRouter:

“Take care of how you handle caching in openrouter. Everytime the provider changes, the cache is gone and you are going to pay full price.” — r/openrouter

Considerale indicazioni utili per la diagnosi, non regole di fatturazione; verifica i costi usando i dati di utilizzo della richiesta, le informazioni sul provider e i prezzi aggiornati di OpenRouter.

FAQ sulla OpenRouter CLI

Queste sono le domande ricorrenti dietro la ricerca openrouter cli. Le risposte brevi qui sotto indicano il livello giusto da controllare: launcher ufficiale, API diretta, client della community o catalogo dei modelli.

Esiste una CLI ufficiale di OpenRouter?

Sì, OpenRouter documenta ufficialmente la CLI ori, ma Ori è un launcher e un livello di configurazione per harness di coding già esistenti. Il pacchetto npm @openrouter/cli di OpenRouter è un’utilità DevTools separata, mentre le CLI per chat e API dirette come @aaronjmars/openroutercli sono progetti della community.

Posso usare OpenRouter da terminale senza installare una CLI?

Sì. Per un prompt singolo basta una richiesta curl autenticata con Bearer verso https://openrouter.ai/api/v1/chat/completions; jq può estrarre il testo oppure conservare il JSON per una pipeline.

Qual è la CLI OpenRouter più adatta per le pipe JSON?

Per uno script piccolo, usare direttamente curl introduce il minor numero di comportamenti nascosti. Per una superficie di comandi più ampia, scegli un client che documenti una modalità JSON, come @aaronjmars/openroutercli, oppure usa llm conservando esplicitamente i dati della risposta che ti servono.

Perché la mia CLI mostra meno modelli del sito OpenRouter?

Un client può memorizzare nella cache il catalogo oppure includere un elenco di modelli precaricato. Confronta il selettore con curl https://openrouter.ai/api/v1/models, aggiorna la cache del client quando possibile e passa l’ID esatto del modello restituito dall’API invece del nome visualizzato.

Ori richiede una chiave API di OpenRouter?

La documentazione di Ori di OpenRouter indica che il normale percorso di accesso usa OAuth PKCE, quindi non è necessario creare e incollare una chiave API separata. curl usato direttamente, llm-openrouter e la maggior parte dei client della community richiedono comunque una chiave o una propria configurazione di autenticazione.

Prima di automatizzare un workflow OpenRouter CLI

Interroga le Models API in tempo reale prima di fissare un modello, registra l’ID del modello e il valore usage della risposta, quindi imposta un budget per l’account o per la chiave. La CLI è soltanto il front-end: modello OpenRouter, route del provider, dimensione del contesto e limiti dell’account restano le variabili che determinano l’affidabilità e il costo del workflow.