OpenUsage ships a one-shot openusage command for agents and scripts. It prints the documented
/v1/limits JSON and exits; it never launches or leaves the menu-bar
app running. The output contains stable scalar limits and balances, not UI rows, colors, subtitles,
charts, or spend-history tiles.
openusage # every enabled provider, refreshing stale cache entries
openusage codex # one provider, refreshing when its cache is stale
openusage codex --force # refresh through the shared provider engine, cache, print, exitThe command and app import the same providers, authentication stores, pricing, refresh coordinator, and
snapshot cache. A normal read reuses snapshots less than five minutes old and refreshes missing or stale
ones. --force is the CLI equivalent of the app's manual refresh: it bypasses that freshness gate and
writes successful results to the same cache. Credentials are used locally and never appear in the output.
A provider argument names providers by plain string matching, exactly like the
local HTTP API: an exact provider ID names that provider, and a family ID
(claude, codex) names every account card of that family — with one account that's exactly the one
card, so existing usage keeps working unchanged as multi-account support arrives. The output envelope
contains every matched provider; an ID that names nothing exits with an error. There is no aliasing
or account-picking logic.
In OpenUsage, open Settings → Command Line and click Install…. After the standard macOS
administrator prompt, openusage is available globally in new terminal sessions. The installed symlink
points to the signed helper inside OpenUsage, so in-place app updates also update the command.
Exit codes are 0 for success, 2 for invalid arguments or an unknown provider, and 4 when a
refresh or local read fails.