CLI Referenz

Zehn Befehle, eine Binary. Agent Tools und Menschen bekommen dieselbe Schnittstelle, und jeder Befehl meldet einen echten Fehler, statt eine Zahl zu erfinden.

Überblick

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.

Installier den globalen Befehl mit npm install -g openlimiter, dann führ jedes Beispiel genau so aus, wie gezeigt.

Die Befehle

init

Schreibt lokale Konfiguration ins Statusverzeichnis und hält jeden Connector und ob er erkannt wurde fest. Es meldet die Liste der erkannten, oder keine.

openlimiter init
Configuration saved. Detected: manual

snapshot

Gibt das gecachte Quota als Tabelle aus. Mit --refresh fragt es zuerst jeden Connector nach Metern, faltet, was die Validierung übersteht, in den Cache ein, und gibt dann aus. Beendet sich mit 3, wenn keine begrenzten Quota Daten existieren.

Acht Spalten, immer acht, durch ein Leerzeichen getrennt, ein Skript kann eine Zeile also aufteilen, ohne zu raten. BAR ist ein zehn Blöcke Meter, gezeichnet in Farbe, wenn das Terminal das unterstützt, und in # und ., wenn nicht oder wenn NO_COLOR gesetzt ist. AMOUNT trägt das Geld für einen Plan, der bepreist statt rationiert ist. RESET ist der Zeitpunkt, an dem sich das Fenster umdreht, und IN ist, wie lange das von jetzt an noch dauert. Eine Spalte ohne etwas zu sagen liest NONE, statt zu verschwinden.

synthetische Werte

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

Ein Connector, dem eine Payload übergeben wurde, die er nicht lesen konnte, oder ein Wert, den der Validator verworfen hat, ergänzt eine Zeile unter der Tabelle in Rot, die den Provider und einen festen Satz benennt. Dieser Satz ist immer einer von uns: Kein Text, den ein Provider gesendet hat, erreicht je dein Terminal.

statusline

Rendert die Statuszeile für einen Statusline Host. Es liest zuerst die Standardeingabe, eine Claude Code Session Payload wird also im selben Aufruf eingelesen und gerendert, und fällt dann auf den Cache zurück. Das ist der einzige Befehl, der als Nebenwirkung des Anzeigens schreibt.

Der übergreifende Reason Code führt, dann die Routingempfehlung, dann eine kompakte Zelle je Provider: ein Name, ein fünf Blöcke Balken, und der Prozentwert. Fünf Blöcke statt der zehn, die die Tabelle zeichnet, weil sich eine Statuszeile mit einem Modellnamen, einem Branch und einem Verzeichnis teilt, und auf einen Blick lesbar sein muss. Der Prozentwert wird gekappt wie überall sonst, ein Balken leuchtet also nie einen Block, den der Wert sich nicht verdient hat.

aufgenommen 10 August 2026, synthetische Fixtures

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%

Abo Provider kommen zuerst, Credit oder API Provider zuletzt, ein Fenster, das sich nach der Uhr auffüllt, steht also nie neben einem Kontostand, der nicht zurückkommt. Innerhalb eines Providers ordnen sich die Meter session, daily, weekly, monthly, credits, und die Zelle zeigt den Meter, der seiner Grenze am nächsten ist. Der vollständige Satz ist ein openlimiter snapshot entfernt, oder setz statusline.meters all, um jeden Meter als eigene Zelle in die Zeile zu bringen.

aufgenommen 10 August 2026, synthetische Fixtures

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%

Eine Zeile, breiter als ihr Budget, stapelt, statt zu kappen. Der Umbruch landet zwischen zwei Zellen und nie innerhalb einer, weil ein halber Balken wie ein Wert aussieht und keiner ist. Zwei Zeilen sind die Obergrenze. Danach werden die Provider behalten, die ihrer Grenze am nächsten sind, und die letzte Zeile endet damit, zu sagen, wie viele sie nicht zeigen konnte.

aufgenommen 10 August 2026, synthetische Fixtures

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

aufgenommen 10 August 2026, synthetische Fixtures

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

Liest und ändert das Statusline Layout in der Konfigurationsdatei. Jeder Schlüssel wird validiert, bevor er geschrieben wird, ein abgelehnter Wert beendet sich mit 2 und benennt, was erwartet wurde, und nichts außerhalb des Statusline Abschnitts kann von diesem Befehl geändert werden. Sieh Konfiguration dafür, was jeder Schlüssel akzeptiert.

aufgenommen 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

Gibt den agent context block aus dem Cache aus. Es führt keinen Netzwerkzugriff aus, schreibt nichts, und injiziert nichts, wenn jeder Provider unknown ist. Sieh Agent context für das genaue Format.

ingest

Nimmt ein Quota Dokument von jedem Skript oder Agenten entgegen, an der Standardeingabe oder inline mit --payload. Ohne --provider ist das Dokument ein manuelles Dokument. Damit geht das Dokument an den Parser dieses Connectors und behält dessen 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

Meldet Connector Erkennung, Aktualität, Drift, und Cache Gesundheit. Drift bleibt UNVERIFIED, bis ein expliziter Verifier existiert, und die Ausgabe ist mit Absicht geschwärzt.

demo

Rendert synthetische Fixtures, damit du die Form der Ausgabe sehen kannst, ganz ohne echtes Konto. Jeder Wert, den es ausgibt, ist erfunden. Der Block unten ist die echte Ausgabe dieses Befehls, unverändert eingefügt.

aufgenommen 10 August 2026, synthetische Fixtures

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

Gibt den Cache als kanonisches JSON aus, geeignet für ein Skript zum Parsen. Beendet sich mit 3, wenn der Cache keine begrenzten Quota Daten hält.

serve

Stellt einen nur lesbaren Snapshot deines Quota in deinem eigenen lokalen Netzwerk bereit, sodass ein Handy im selben Netzwerk ihn sehen kann. Gibt die Adresse und einen QR Code zum Scannen aus. Bei jedem Start des Befehls wird ein frisches Token erzeugt, und es reist im URL Fragment nach #t=, das ein Server nie erhält. Die Seite bewegt dieses Token in das eigene sessionStorage des Tabs und säubert die Adressleiste beim ersten Laden, keine Browserhistorie hält diese Fähigkeit also irgendwo fest. Jeder erneute Abruf danach sendet das Token als Authorization: Bearer Header statt als URL Parameter. Eine Adresse, die der letzte Release ausgegeben hat, mit dem Token als Query Parameter, antwortet für dieses eine Release noch, nichts bereits Gescanntes oder Gespeichertes bricht also.

Exit Codes

Exit Codes und was sie bedeuten
Code	Bedeutung
`0`	Erfolg.
`1`	Ein echter Fehler.
`2`	Ein Usage Fehler, etwa eine unbekannte Provider id.
`3`	Keine begrenzten Quota Daten verfügbar.

Verhalten, das es zu kennen lohnt

Die Standardeingabe ist begrenzt und zeitlich beschränkt, ein Befehl wartet also nie auf einen Stream, der nicht endet.
Angezeigte Prozentwerte werden gekappt statt gerundet, keine Oberfläche kann also eine Grenze melden, die nicht erreicht wurde.
--provider und --payload brauchen je einen Wert. Das Flag ohne Wert zu übergeben, ist ein Usage Fehler.
In diesem Release erreicht kein Befehl das Netzwerk. Jeder Weg ist ein Parser über etwas, das schon auf deinem Rechner liegt.