CLI reference

Eight commands, one binary. Agent tools and people get the same interface, and every command reports a genuine failure rather than inventing a number.

Overview

openlimiter help

openlimiter init
openlimiter snapshot [--refresh]
openlimiter statusline
openlimiter hook [--dry-run]
openlimiter ingest [--provider <id>] [--payload <json>]
openlimiter doctor
openlimiter demo
openlimiter export

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.

The package is not published yet, so run these as pnpm openlimiter <command> or node packages/cli/dist/bin.js <command> from the repository root.

The commands

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.

synthetic values

openlimiter snapshot
PROVIDER METER USAGE STATE RESET
CLAUDE FIVE_HOUR 42.00PERCENT fresh 2026-08-09T20:35:37.671Z
CLAUDE SEVEN_DAY 64.00PERCENT fresh 2026-08-16T15:35:37.671Z

statusline

Renders one line 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.

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.

captured 9 August 2026, synthetic fixtures

node packages/cli/dist/bin.js demo
PROVIDER METER USAGE STATE RESET
CLAUDE FIVE_HOUR 42.00PERCENT fresh 2026-08-09T20:35:38.724Z
CLAUDE SEVEN_DAY 64.00PERCENT fresh 2026-08-16T15:35:38.724Z
OPENROUTER CREDITS 37.00PERCENT fresh NONE
CODEX PRIMARY 51.00PERCENT fresh 2026-08-09T20:35:38.724Z
ANTIGRAVITY PRIMARY 28.00PERCENT fresh 2026-08-10T15:35:38.724Z
OPENCODE PRIMARY 73.00PERCENT fresh 2026-08-10T15:35:38.724Z
MANUAL MONTHLY 35.00PERCENT fresh 2026-09-09T15:35:38.724Z

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

Exit codes and what they mean
code	meaning
`0`	Success.
`1`	A genuine failure.
`2`	A usage error, such as an unknown provider id.
`3`	No bounded quota data is available.

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.
In this release no command reaches the network. Every path is a parser over something already on your machine.