CLI reference

Overview

openlimiter
openlimiter setup
openlimiter login [--open]
openlimiter logout
openlimiter whoami
openlimiter sync
openlimiter init
openlimiter snapshot [--refresh]
openlimiter statusline [--host claude|antigravity|grok|codex|shell]
openlimiter terminal [--yes] [--host <id>]
openlimiter terminal status
openlimiter terminal install <host>
openlimiter terminal uninstall <host>
openlimiter terminal show <provider ...>
openlimiter terminal hide <provider ...>
openlimiter refresh
openlimiter hook [--dry-run]
openlimiter hooks install <agent>
openlimiter hooks uninstall <agent>
openlimiter hooks status <agent>
openlimiter hooks repair <agent>
openlimiter status --agent-context
openlimiter ingest [--provider <id>] [--payload <json>]
openlimiter config get statusline[.<key>]
openlimiter config set statusline.<key> <value>
openlimiter config get providers[.<key>]
openlimiter config set providers.<key> <value>
openlimiter doctor
openlimiter demo
openlimiter export

statusline keys: order, meters, width, rows, bars, color, style, show, hosts.
providers keys: claude.poll.
terminal hosts: claude, antigravity, grok, codex, shell.
statusline and ingest read JSON from standard input when it is piped in.
openlimiter with no arguments runs setup: sign in, connect, show bars in.
login opens the device code sign in; sync uploads one round to the hub when
a session exists, and refresh triggers it automatically after itself.
refresh reads the logins your provider tools already stored on this machine
and asks each provider for its own usage, at most once every 15 minutes. It
stands down while the desktop app is running. statusline and snapshot start
it in the background when the cache is older than a minute.
Exit codes: 0 success, 1 failure, 2 usage, 3 no bounded quota data.

Install the global command with npm install -g openlimiter, or run it once with npx openlimiter.

The commands

setup

Ejecuta los mismos tres pasos que openlimiter sin argumentos: iniciar sesión, conectar y elegir dónde mostrar barras. Después muestra las barras una vez. Los pasos omitidos siguen omitidos; ninguno es obligatorio para ver una barra.

login

Inicia sesión en este terminal mediante un código de dispositivo: aparecen un código corto y el enlace openlimiter.com/app/cli, y el comando espera tu aprobación allí. --open también abre el enlace en el navegador. El terminal nunca ve una contraseña.

logout

Olvida la sesión guardada en este dispositivo. No solicita ninguna acción al centro.

whoami

Muestra la cuenta con sesión iniciada y el identificador del dispositivo, o indica claramente que nadie ha iniciado sesión.

sync

Sube una ronda de barras en caché al centro y renueva primero la sesión si está próxima a caducar. refresh ya lo hace automáticamente tras una ronda correcta cuando existe una sesión. La ejecución manual sirve para comprobar que la transferencia llegó.

init

Writes local configuration to the state directory, recording every connector and whether it was detected. It reports the detected list, or none.

openlimiter init
Configuration saved. Detected: manual

snapshot

Prints the cached quota as a table. With --refresh it first asks every connector for meters, folds what survives validation into the cache, and then prints. Exits 3 when no bounded quota data exists.

Eight columns, always eight, separated by one space, so a script can split a row without guessing. BAR is a ten block meter, drawn in colour when the terminal supports it and in # and . when it does not or when NO_COLOR is set. AMOUNT carries the money for a plan that is priced rather than rationed. RESET is the instant the window turns over and IN is how long that is from now. A column with nothing to say reads NONE rather than disappearing.

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

A connector that was handed a payload and could not read it, or a reading the validator threw out, adds one line under the table in red, naming the provider and one fixed sentence. That sentence is always one of ours: no text a provider sent ever reaches your terminal.

statusline

Renders the status row for a statusline host. It reads standard input first, so a Claude Code session payload is ingested and rendered in the same call, then falls back to the cache. This is the only command that writes as a side effect of being displayed.

The default layout draws one cell per window for the host named by <code>--host</code>: a tag, a ten block bar, the percentage, and the reset time, with no header line at all. See <docs>agent context</docs> for the full grammar and the freshness marks.

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%

statusline.style cells brings back the previous row instead: the overall reason code and the routing recommendation lead, then one compact cell per provider with a five block bar rather than the ten the new default draws.

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%

A row wider than its budget stacks rather than truncating. The break lands between two cells and never inside one, because half a bar reads as a reading and is not one. Two rows is the ceiling. Past that the providers closest to their caps are kept, and the last row ends by saying how many it could not show.

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

terminal

Enumera los terminales compatibles y su configuración, y ofrece configurar uno o todos. terminal install <host> y terminal uninstall <host> configuran o restauran un terminal. terminal status muestra la tabla, y terminal show y terminal hide eligen los proveedores visibles. Consulta contexto del agente para conocer los terminales y el formato.

refresh

Lee las sesiones guardadas por tus herramientas y pide a cada proveedor su uso como máximo una vez cada quince minutos. Guarda en caché las lecturas válidas. Se detiene mientras la aplicación de escritorio está abierta. <code>statusline</code> y <code>snapshot</code> lo inician automáticamente en segundo plano cuando la caché supera un minuto.

config

Reads and changes the statusline layout in the configuration file. Every key is validated before it is written, a rejected value exits 2 and names what it wanted, and nothing outside the statusline section can be changed by this command. See configuration for what each key accepts.

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.

openlimiter config set providers.claude.poll true
providers.claude.poll=true

hook

Emits the agent context block from the cache. It performs no network access, writes nothing, and injects nothing when every provider is unknown. See agent context for the exact format.

ingest

Accepts a quota document from any script or agent, on standard input or inline with --payload. Without --provider the document is a manual document. With it, the document goes to that connector's parser and keeps that connector's labels.

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

Reports connector detection, freshness, drift, and cache health. Drift stays UNVERIFIED until an explicit verifier exists, and the output is redacted by design.

demo

Renders synthetic fixtures so you can see the output shape without any real account. Every value it prints is invented. The block below is the real output of that command, pasted in unedited.

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

Prints the cache as canonical JSON, suitable for a script to parse. Exits 3 when the cache holds no bounded quota data.

Exit codes

Behaviour worth knowing

• Standard input is bounded and time limited, so a command never waits on a stream that does not end.
• Displayed percentages are truncated rather than rounded, so no surface can report a cap that was not reached.
• --provider and --payload each need a value. Passing the flag without one is a usage error.
• Only login, sync and refresh reach the network, and only to the hub or to a provider whose login is already on this machine. Every other command is a parser over something already local.