OpenRouter CLI: Ori, curl, llm e aichat

Quem procura um OpenRouter CLI acaba encontrando duas respostas diferentes. O comando oficial ori da OpenRouter configura e inicia agentes de programação já existentes, enquanto os clientes da comunidade oferecem prompts únicos, chat em REPL, saída em JSON ou uma cobertura mais ampla da API. Se a sua necessidade é apenas montar um pipeline no shell, a API da OpenRouter e o curl já resolvem.

O que “OpenRouter CLI” significa na prática

“OpenRouter CLI” não é o nome de um único cliente oficial e universal para o terminal. Na prática, o termo engloba três fluxos diferentes: iniciar um agente pela OpenRouter, chamar a API diretamente no shell ou usar uma ferramenta de terminal de terceiros, como llm ou aichat.

A distinção mais importante envolve autoria e escopo. A integração ori da OpenRouter e o pacote oficial @openrouter/cli para DevTools são oficiais, mas nenhum dos dois é um cliente genérico do tipo openrouter ask: o pacote DevTools se concentra em um visualizador de telemetria do SDK e em uma linha de status para o Claude Code, enquanto o Ori inicia harnesses já existentes.

O caminho oficial: instale e use o Ori Harness

O Ori é o CLI oficial da OpenRouter para configurar harnesses compatíveis de agentes de programação. Ele autentica na OpenRouter, envia o modelo selecionado ao agente subjacente e preserva os comandos e parâmetros habituais desse agente. Ou seja, não substitui o Claude Code, o Codex, o OpenCode nem os demais harnesses.

Instale a ferramenta usando o comando divulgado no anúncio e no guia da OpenRouter:

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

Depois, faça a autenticação e inicie um agente:

ori login
ori claude
ori codex
ori opencode
ori hermes

A documentação atual do Ori também lista grok, pi, prime-agent e dsh entre os comandos compatíveis. O comando ori dsh configura o DeepSeek Harness, mas não o inicia; depois, execute dsh. Para atualizar o Ori, use ori update.

Escolha o modelo sem trocar de agente

O Ori aceita um ID de modelo da OpenRouter e encaminha os argumentos não reconhecidos ao harness subjacente:

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

Os detalhes do endpoint variam entre os agentes. Nas orientações da OpenRouter para o Claude Code, por exemplo, é usada a URL base compatível com Anthropic https://openrouter.ai/api, enquanto clientes compatíveis com OpenAI, como o Codex, usam https://openrouter.ai/api/v1. O Ori existe, em parte, para esconder essas diferenças de configuração entre os harnesses.

O Ori usa OAuth PKCE baseado no navegador. Por isso, no fluxo normal, não é preciso colar uma chave de API da OpenRouter em cada agente. A documentação do Ori Harness informa que as requisições seguem o faturamento e os relatórios de atividade padrão da OpenRouter, sem uma cobrança separada do Ori. O custo de inferência continua sendo determinado pelo modelo selecionado e pelo harness utilizado.

O Ori não é um REPL de chat independente

Use o Ori quando você já quer as ferramentas, as operações de arquivos ou o modelo de aprovação de um agente. Prefira curl, um cliente direto, llm ou aichat quando a tarefa for apenas um prompt, uma resposta estruturada ou um pipeline de shell que não deve iniciar um agente de programação.

Essa fronteira é importante porque o material oficial de lançamento apresenta o Ori como uma camada de compatibilidade e configuração. O pacote oficial @openrouter/cli é outra fonte de confusão: os comandos documentados atualmente são openrouter devtools e openrouter statusline, e a linha 1.0 removeu comandos de proxy anteriores, como start, stop, restart e code.

Clientes comunitários da OpenRouter que vale conhecer

Os clientes da comunidade se diferenciam pela interface que oferecem no terminal. A escolha prática depende de você precisar de um seletor interativo, cobertura completa da API, um binário pequeno, automação com vários modelos ou uma saída previsível e legível por máquinas.

Esses são recursos documentados, não benchmarks de desempenho comparáveis.

O fluxo mais enxuto e confiável: curl e jq

Se o curl e o jq já estão instalados, a API bruta da OpenRouter é o caminho mais simples e transparente pelo terminal. O Quickstart da OpenRouter documenta a autenticação Bearer, o endpoint compatível com OpenAI /api/v1/chat/completions, o campo model, o array messages e o streaming opcional.

Defina a chave e o modelo na sessão do shell:

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

Em seguida, envie um 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'

Use uma variável de ambiente para o modelo, em vez de copiar um ID para cada script. A API oficial de Modelos informa o id, o tamanho do contexto, os preços, os parâmetros compatíveis, os limites dos provedores e, opcionalmente, metadados de benchmarks.

Transforme a requisição em funções reutilizáveis do shell

Estas funções mantêm o corpo da requisição seguro para JSON, deixando que o jq faça a codificação do prompt. A função orask recebe um argumento; orpipe lê toda a entrada padrão como um único 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)"
}

Exemplos:

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

Se o script precisar de metadados, mantenha o JSON em vez de extrair apenas o texto:

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 @-
}

Assim, o objeto usage da resposta continua disponível para contabilizar custos, e os erros da API podem ser diferenciados de uma resposta vazia do modelo.

Descubra modelos compatíveis pela linha de comando

Um modelo presente no catálogo não necessariamente aceita todos os parâmetros de requisição. A API de Modelos da OpenRouter permite filtrar por supported_parameters, incluindo tools, e ordenar por preço, contexto, throughput, latência, popularidade ou recência.

Liste os modelos compatíveis com ferramentas começando pelos mais baratos na ordenação documentada:

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

Confira um modelo antes de colocá-lo em um script de produção. A OpenRouter documenta a rota singular de detalhes do modelo como /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}'

Os valores de pricing são expressos por token ou unidade. Portanto, não interprete um decimal bruto como um valor em dólares por milhão sem fazer a conversão. O campo usage da resposta é a fonte mais segura para verificar quantos tokens de entrada e saída foram realmente consumidos.

Processamento em lote com um pipeline de shell

Um fluxo útil para processamento em lote é ter um prompt por linha em um arquivo de texto e um objeto JSON por resultado. O script abaixo registra o prompt original, a resposta, o uso e um campo de erro, sem misturar o texto do modelo com a saída legível por máquinas.

Crie o arquivo prompts.txt:

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

Execute o lote:

#!/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

O script executa as requisições em sequência. Só adicione concorrência depois de conferir os limites de requisição e o orçamento, porque chamadas paralelas podem aumentar os custos rapidamente. A página de preços da OpenRouter informa 50 requisições por dia no plano gratuito e uma tarifa de plataforma de 5,5% no modelo pay-as-you-go. Portanto, um modelo gratuito não representa capacidade ilimitada para processamento em lote.

Onde entram o llm e o aichat

llm e aichat são ferramentas gerais de trabalho no terminal que oferecem suporte à OpenRouter. Elas fazem mais sentido do que um wrapper pequeno quando você precisa de prompts reutilizáveis, sessões, anexos, ferramentas, modelos locais ou um histórico do trabalho anterior.

llm-openrouter: a opção com logs e extensível

Primeiro instale o comando base llm e depois adicione o plugin da OpenRouter:

llm install llm-openrouter
llm keys set openrouter

O plugin documenta OPENROUTER_KEY como nome da variável de ambiente. Ele disponibiliza modelos da OpenRouter com nomes como openrouter/anthropic/claude-sonnet-5, mantém a lista de modelos em cache por uma hora e permite atualizá-la com:

llm openrouter refresh
llm models list

Um prompt normal e um pipeline de shell ficam assim:

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"

O plugin documenta schemas, anexos, chamadas de ferramentas, opções de raciocínio, JSON para roteamento de provedores, ferramentas web da OpenRouter e inspeção de chaves. É um meio-termo entre o curl puro e um harness autônomo de programação, mas o cache de modelos pode ficar defasado em relação ao catálogo ao vivo.

aichat: uma ferramenta de terminal mais abrangente

O aichat é um CLI baseado em Rust que oferece suporte à OpenRouter, além de mais de 20 provedores nomeados e endpoints compatíveis com OpenAI. Sua interface documentada inclui modo CMD, Chat-REPL, assistência de shell, sessões, macros, RAG, chamadas de funções, ferramentas MCP, agentes e um servidor local com endpoints de chat, embeddings e reranking.

A configuração da OpenRouter usa um cliente compatível com OpenAI apontado para https://openrouter.ai/api/v1, e os exemplos do projeto usam o formato de modelo openrouter:<model>. Escolha essa opção quando o terminal estiver se tornando a interface da sua aplicação; prefira curl ou llm quando quiser um caminho de requisição menor e mais fácil de inspecionar.

Diagnosticando falhas que parecem ser problema do CLI

Falhas em um CLI da OpenRouter podem acontecer na fronteira entre o shell, o cliente, o modelo selecionado e a conta. Antes de trocar de ferramenta, diagnostique cada camada separadamente.

Em uma discussão no Reddit sobre OpenCode e Kilo Code, o usuário u/GrevireDev escreveu:

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

Em outra discussão sobre a OpenRouter, o usuário u/DrunkenRobotBipBop fez a seguinte observação sobre custos e cache:

“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

Use esses relatos como pistas para investigar problemas, não como regras de cobrança. Confirme os custos usando o uso da requisição, os dados do provedor e os preços atuais da OpenRouter.

FAQ sobre o OpenRouter CLI

Estas são as dúvidas recorrentes por trás da busca por openrouter cli. As respostas curtas abaixo apontam para a camada certa: lançador oficial, API bruta, cliente comunitário ou catálogo de modelos.

Existe um CLI oficial da OpenRouter?

Sim. A OpenRouter documenta oficialmente o CLI ori, mas ele é uma camada de lançamento e configuração para harnesses existentes de agentes de programação. O pacote npm @openrouter/cli da OpenRouter é uma ferramenta DevTools separada, enquanto CLIs para chat e API direta, como @aaronjmars/openroutercli, são projetos da comunidade.

Posso usar a OpenRouter no terminal sem instalar um CLI?

Sim. Uma requisição curl autenticada com Bearer para https://openrouter.ai/api/v1/chat/completions basta para enviar um prompt único, e o jq pode extrair o texto ou preservar o JSON para um pipeline.

Qual é o melhor OpenRouter CLI para fazer pipe de JSON?

Para um script pequeno, o curl direto oferece menos comportamentos ocultos. Para uma interface com mais comandos, escolha um cliente que documente um modo JSON, como o @aaronjmars/openroutercli, ou use o llm preservando explicitamente os dados da resposta de que você precisa.

Por que meu CLI mostra menos modelos do que o site da OpenRouter?

O cliente pode manter o catálogo em cache ou incluir uma lista de modelos pré-carregada. Compare o seletor com curl https://openrouter.ai/api/v1/models, atualize o cache do cliente quando houver suporte e passe o ID exato do modelo retornado pela API, em vez do nome exibido na interface.

O Ori exige uma chave de API da OpenRouter?

A documentação do Ori informa que o fluxo normal de login usa OAuth PKCE. Assim, o usuário não precisa criar e colar uma chave de API separada. O curl puro, o llm-openrouter e a maioria dos clientes comunitários ainda exigem uma chave ou sua própria configuração de autenticação.

Antes de automatizar um fluxo com o OpenRouter CLI

Consulte a API de Modelos em tempo real antes de fixar um modelo, registre o ID do modelo e o usage da resposta e estabeleça um limite para a conta ou para a chave. O CLI é apenas a interface: o modelo da OpenRouter, a rota do provedor, o tamanho do contexto e os limites da conta continuam sendo as variáveis que determinam se o fluxo será confiável e acessível.