Referência da CLI

Visão geral

openlimiter init
openlimiter snapshot [--refresh]
openlimiter statusline
openlimiter hook [--dry-run]
openlimiter ingest [--provider <id>] [--payload <json>]
openlimiter config get statusline[.<key>]
openlimiter config set statusline.<key> <value>
openlimiter doctor
openlimiter demo
openlimiter export
openlimiter serve [--port <n>] [--host <address>] [--no-qr]

statusline keys: order, meters, width, rows, bars, color.
statusline and ingest read JSON from standard input when it is piped in.
Exit codes: 0 success, 1 failure, 2 usage, 3 no bounded quota data.

Instale o comando global com npm install -g openlimiter, e depois rode cada exemplo exatamente como mostrado.

Os comandos

init

Escreve a configuração local no diretório de estado, registrando cada connector e se ele foi detectado. Reporta a lista detectada, ou nenhuma.

openlimiter init
Configuration saved. Detected: manual

snapshot

Imprime a quota em cache como uma tabela. Com --refresh, primeiro pergunta a cada connector por meters, funde o que sobrevive à validação no cache, e então imprime. Sai com 3 quando não existe nenhum dado de quota limitado.

Oito colunas, sempre oito, separadas por um espaço, para um script poder dividir uma linha sem chutar. BAR é um meter de dez blocos, desenhado em cor quando o terminal suporta, e em # e . quando não suporta, ou quando NO_COLOR está definida. AMOUNT carrega o dinheiro para um plano que é precificado em vez de racionado. RESET é o instante em que a janela vira, e IN é quanto tempo falta a partir de agora. Uma coluna sem nada a dizer mostra NONE em vez de desaparecer.

openlimiter snapshot
PROVIDER METER BAR USAGE AMOUNT STATE RESET IN
CLAUDE FIVE_HOUR ####...... 42.00PERCENT NONE fresh 2026-08-10T04:00:32.969Z 5h0m
CLAUDE SEVEN_DAY ######.... 64.00PERCENT NONE fresh 2026-08-16T23:00:32.969Z 7d0h
OPENROUTER CREDITS ######.... 62.35PERCENT $12.47/$20.00 fresh NONE NONE

Um connector que recebeu um payload que não conseguiu interpretar, ou uma leitura que o validador descartou, adiciona uma linha embaixo da tabela em vermelho, nomeando o provedor e uma frase fixa. Essa frase é sempre nossa: nenhum texto que um provedor enviou chega ao seu terminal.

statusline

Renderiza a linha de status para um host de statusline. Ele lê a entrada padrão primeiro, então um payload de sessão do Claude Code é ingerido e renderizado na mesma chamada, depois recorre ao cache. Este é o único comando que escreve como efeito colateral de ser exibido.

O código de motivo geral vem à frente, depois a recomendação de roteamento, depois uma célula compacta por provedor: um nome, uma barra de cinco blocos, e a porcentagem. Cinco blocos em vez dos dez que a tabela desenha, porque uma linha de status é compartilhada com um nome de modelo, uma branch e um diretório, e precisa ser lida de relance. A porcentagem é truncada como em qualquer outro lugar, então uma barra nunca acende um bloco que a leitura não ganhou.

NO_COLOR=1 node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP PREFER ANTIGRAVITY  CLAUDE ###.. 64.0%  CODEX ####. 84.0%  ANTIGRAVITY #.... 28.0%  OPENCODE ####. 92.0%
MANUAL #.... 35.0%  OPENROUTER ###.. 62.3%

Provedores de assinatura vêm primeiro e provedores de crédito ou API por último, então uma janela que se enche num relógio nunca é lida ao lado de um saldo que não volta. Dentro de um provedor, os meters seguem a ordem sessão, diário, semanal, mensal, créditos, e a célula mostra o meter mais próximo do limite dele. O conjunto completo está a um openlimiter snapshot de distância, ou defina statusline.meters all para colocar cada meter na linha como sua própria célula.

openlimiter config set statusline.meters all && NO_COLOR=1 node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP PREFER ANTIGRAVITY  CLAUDE:FIVE_HOUR ##... 42.0%  CLAUDE:SEVEN_DAY ###.. 64.0%  CODEX:PRIMARY ####. 84.0%
ANTIGRAVITY:PRIMARY #.... 28.0%  OPENCODE:PRIMARY ####. 92.0%  MANUAL:MONTHLY #.... 35.0%  OPENROUTER:CREDITS ###.. 62.3%

Uma linha mais larga que seu orçamento empilha em vez de truncar. A quebra acontece entre duas células e nunca dentro de uma, porque meia barra parece uma leitura e não é uma. Duas linhas é o teto. Além disso, os provedores mais perto do limite deles são mantidos, e a última linha termina dizendo quantos ela não conseguiu mostrar.

openlimiter config set statusline.rows 1 && NO_COLOR=1 node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP PREFER ANTIGRAVITY  CODEX ####. 84.0%  OPENCODE ####. 92.0%  +4 more

openlimiter config set statusline.bars false && node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP CLAUDE 64.0% OPENROUTER 62.3% CODEX 84.0% ANTIGRAVITY 28.0% OPENCODE 92.0% MANUAL 35.0% PREFER ANTIGRAVITY

config

Lê e altera o layout do statusline no arquivo de configuração. Toda chave é validada antes de ser escrita, um valor rejeitado sai com 2 e nomeia o que esperava, e nada fora da seção de statusline pode ser alterado por este comando. Veja configuração para o que cada chave aceita.

openlimiter config get statusline
statusline.order=NONE
statusline.meters=worst
statusline.width=140
statusline.rows=2
statusline.bars=true
statusline.color=auto

openlimiter config set statusline.width 200
statusline.width=200

openlimiter config set statusline.rows 3
openlimiter config: statusline.rows must be 1 or 2.

hook

Emite o bloco de agent context a partir do cache. Não faz nenhum acesso de rede, não escreve nada, e não injeta nada quando todo provedor está unknown. Veja agent context para o formato exato.

ingest

Aceita um documento de quota de qualquer script ou agente, pela entrada padrão ou inline com --payload. Sem --provider, o documento é um documento manual. Com ele, o documento vai para o parser daquele connector e mantém os rótulos daquele connector.

openlimiter ingest --payload '{"meters":[{"name":"AGENT_BUDGET","used_percent":12.5,"reset_at":"2026-08-09T13:11:30.141Z"}]}'
Ingested 1 bounded meters. Cached meters: 3.

doctor

Reporta detecção de connector, atualização, desvio, e saúde do cache. Desvio continua UNVERIFIED até existir um verificador explícito, e a saída é redigida por design.

demo

Renderiza fixtures sintéticos para você ver o formato da saída sem nenhuma conta real. Todo valor que ele imprime é inventado. O bloco abaixo é a saída real desse comando, colada sem edição.

NO_COLOR=1 node packages/cli/dist/bin.js demo
PROVIDER METER BAR USAGE AMOUNT STATE RESET IN
CLAUDE FIVE_HOUR ####...... 42.00PERCENT NONE fresh 2026-08-10T09:12:01.000Z 4h59m
CLAUDE SEVEN_DAY ######.... 64.00PERCENT NONE fresh 2026-08-17T04:12:01.000Z 6d23h
OPENROUTER CREDITS ######.... 62.35PERCENT $12.47/$20.00 fresh NONE NONE
CODEX PRIMARY ########.. 84.00PERCENT NONE fresh 2026-08-10T09:12:01.658Z 5h0m
ANTIGRAVITY PRIMARY ##........ 28.00PERCENT NONE fresh 2026-08-11T04:12:01.658Z 1d0h
OPENCODE PRIMARY #########. 92.00PERCENT NONE fresh 2026-08-11T04:12:01.658Z 1d0h
MANUAL MONTHLY ###....... 35.00PERCENT NONE fresh 2026-09-10T04:12:01.658Z 31d0h

export

Imprime o cache como JSON canônico, adequado para um script interpretar. Sai com 3 quando o cache não guarda nenhum dado de quota limitado.

serve

Serve um snapshot só para leitura da sua quota na sua própria rede local, para um celular na mesma rede poder ver isso. Imprime o endereço e um código QR para escanear. Um token novo é gerado toda vez que o comando inicia, e ele viaja no fragmento da URL depois de #t=, que um servidor nunca recebe. A página move esse token para o próprio sessionStorage da aba e limpa a barra de endereço no primeiro carregamento, então nenhum histórico de navegador em lugar nenhum guarda a capacidade. Toda nova busca depois disso envia o token como um cabeçalho Authorization: Bearer, em vez de um parâmetro de URL. Um endereço impresso pelo último release, com o token como parâmetro de consulta, ainda funciona neste release, então nada já escaneado ou salvo quebra.

Códigos de saída

Comportamento que vale a pena saber

• A entrada padrão é limitada e tem tempo limite, então um comando nunca espera por um stream que não termina.
• Porcentagens exibidas são truncadas em vez de arredondadas, então nenhuma superfície pode reportar um limite que não foi alcançado.
• --provider e --payload precisam cada um de um valor. Passar a flag sem um é um erro de uso.
• Nesta versão, nenhum comando alcança a rede. Todo caminho é um parser sobre algo já na sua máquina.