Referencia de la CLI

Diez órdenes, un binario. Las herramientas de agentes y las personas usan la misma interfaz, y cada orden reporta un fallo genuino en vez de inventar un número.

Resumen

openlimiter help

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.

Instala la orden global con npm install -g openlimiter, y luego corre cada ejemplo exactamente como se muestra.

Las órdenes

init

Escribe la configuración local en el directorio de estado, registrando cada connector y si fue detectado. Reporta la lista detectada, o ninguna.

openlimiter init
Configuration saved. Detected: manual

snapshot

Imprime la quota en caché como tabla. Con --refresh primero le pide meters a cada connector, pliega lo que sobrevive la validación dentro de la caché, y luego imprime. Sale con 3 cuando no existen datos de quota acotados.

Ocho columnas, siempre ocho, separadas por un espacio, así que un script puede dividir una fila sin adivinar. BAR es un meter de diez bloques, dibujado a color cuando la terminal lo admite, y con # y . cuando no lo admite o cuando NO_COLOR está definida. AMOUNT lleva el dinero para un plan que tiene precio en vez de ración. RESET es el instante en que la ventana se reinicia, e IN es cuánto falta para eso desde ahora. Una columna sin nada que decir se lee NONE en vez de desaparecer.

valores sintéticos

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

Un connector al que se le entregó una carga y no la pudo leer, o una lectura que el validador descartó, agrega una línea debajo de la tabla en rojo, nombrando al proveedor y una frase fija. Esa frase siempre es nuestra: ningún texto que envió un proveedor llega jamás a tu terminal.

statusline

Renderiza la fila de estado para un host de statusline. Lee primero la entrada estándar, así que una carga de sesión de Claude Code se ingiere y se renderiza en la misma llamada, y luego recurre a la caché. Esta es la única orden que escribe como efecto secundario de mostrarse.

El código de motivo general va al frente, luego la recomendación de enrutamiento, luego una celda compacta por proveedor: un nombre, una barra de cinco bloques y el porcentaje. Cinco bloques en vez de los diez que dibuja la tabla, porque una fila de estado se comparte con un nombre de modelo, una rama y un directorio, y tiene que leerse de un vistazo. El porcentaje se trunca igual que en todos lados, así que una barra nunca enciende un bloque que la lectura no se ganó.

capturado el 10 August 2026, datos sintéticos

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%

Los proveedores de suscripción van primero, y los de crédito o API al final, así que una ventana que se recarga en un reloj nunca se lee junto a un saldo que no vuelve. Dentro de un proveedor, los meters se ordenan sesión, diario, semanal, mensual, créditos, y la celda muestra el meter más cercano a su límite. El conjunto completo está a un openlimiter snapshot de distancia, o define statusline.meters all para poner cada meter en la fila como su propia celda.

capturado el 10 August 2026, datos sintéticos

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%

Una fila más ancha que su presupuesto se apila en vez de truncarse. El salto cae entre dos celdas y nunca dentro de una, porque media barra se lee como una lectura y no lo es. Dos filas es el límite. Pasado eso, se conservan los proveedores más cercanos a su límite, y la última fila termina diciendo cuántos no pudo mostrar.

capturado el 10 August 2026, datos sintéticos

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

capturado el 10 August 2026, datos sintéticos

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

Lee y cambia el layout del statusline en el archivo de configuración. Cada clave se valida antes de escribirse, un valor rechazado sale con 2 y nombra lo que esperaba, y esta orden no puede cambiar nada fuera de la sección del statusline. Consulta configuración para ver qué acepta cada clave.

capturado el 10 August 2026

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 el bloque de agent context desde la caché. No realiza ningún acceso de red, no escribe nada y no inyecta nada cuando todos los proveedores están unknown. Consulta agent context para ver el formato exacto.

ingest

Acepta un documento de quota de cualquier script o agente, por entrada estándar o en línea con --payload. Sin --provider, el documento es un documento manual. Con eso, el documento va al parser de ese connector y conserva las etiquetas de ese 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 la detección de connectors, la vigencia, la deriva y la salud de la caché. La deriva se queda como UNVERIFIED hasta que exista un verificador explícito, y la salida está redactada por diseño.

demo

Renderiza datos sintéticos para que veas la forma de la salida sin ninguna cuenta real. Cada valor que imprime está inventado. El bloque de abajo es la salida real de esa orden, pegada sin editar.

capturado el 10 August 2026, datos sintéticos

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 la caché como JSON canónico, apto para que lo analice un script. Sale con 3 cuando la caché no tiene datos de quota acotados.

serve

Sirve una instantánea de solo lectura de tu quota en tu propia red local, así que un teléfono en la misma red la puede ver. Imprime la dirección y un código QR para escanear. Se genera un token nuevo cada vez que arranca la orden, y viaja en el fragmento de la URL después de #t=, que un servidor nunca recibe. La página mueve ese token al propio sessionStorage de la pestaña y limpia la barra de direcciones en la primera carga, así que ningún historial del navegador en ningún lado guarda esa capacidad. Cada nueva consulta después de eso envía el token como un encabezado Authorization: Bearer en vez de como parámetro de URL. Una dirección impresa por el release anterior, con el token como parámetro de consulta, sigue respondiendo para este mismo release, así que nada de lo ya escaneado o guardado se rompe.

Códigos de salida

Códigos de salida y qué significan
código	significado
`0`	Éxito.
`1`	Un fallo genuino.
`2`	Un error de uso, como un id de proveedor desconocido.
`3`	No hay datos de quota acotados disponibles.

Comportamiento que vale la pena conocer

La entrada estándar está acotada y tiene tiempo límite, así que una orden nunca espera a un flujo que no termina.
Los porcentajes mostrados se truncan en vez de redondearse, así que ninguna superficie puede reportar un límite que no se alcanzó.
--provider y --payload necesitan cada una un valor. Pasar la opción sin uno es un error de uso.
En este release ninguna orden llega a la red. Cada ruta es un parser sobre algo que ya está en tu máquina.