llm-usage-meter
Check your remaining LLM credits and quota across providers — from the terminal, in one command.
- Zero dependencies. Pure Python stdlib on Linux/macOS; on Windows pip
auto-installs only the tiny
windows-cursesshim for the dashboard. - Never costs credits. Only free endpoints are used: billing/balance APIs, the free
count_tokensprobe, and model lists. No inference calls, ever. - General & extensible. Add a provider in ~30 lines.
● Anthropic
Requests left / min 48 / 50 █████████████████████░ 96%
Input tokens left / min 39,214 / 40,000 ██████████████████████ 98%
live rate-limit headers via free count_tokens probe; no credits consumed
● OpenRouter
Credits left $12.06 / $25.00 ███████████░░░░░░░░░░░ 48%
Used (lifetime) $12.94
prepaid balance from /credits
● DeepSeek
Usable yes
Balance (USD) $4.87
account balance from /user/balance
Meters are color-coded (green > 50%, yellow > 20%, red below) and
llm-usage-meter -w 60 turns this into a live full-screen dashboard that
refreshes every 60 seconds.
Install
From PyPI:
pip install llm-usage-meter # recommended
# or
pipx install llm-usage-meter # isolated, CLI on your PATH
Configure
Set the environment variables for the providers you use — that's it:
| Provider | Env var | What you get |
|---|---|---|
| OpenRouter | OPENROUTER_API_KEY |
Prepaid credits remaining (real $ balance) |
| DeepSeek | DEEPSEEK_API_KEY |
Account balance (real $ balance) |
| Anthropic | ANTHROPIC_API_KEY |
Live per-minute rate limits remaining |
| Gemini | GEMINI_API_KEY |
Key health + free quota probe (OK/rate-limited) |
| OpenAI | OPENAI_ADMIN_KEY |
Month-to-date spend (org admin key required) |
| xAI | XAI_API_KEY |
Key health / blocked status |
| Groq | GROQ_API_KEY |
Key status + rate-limit headers when available |
Providers without a key are skipped silently.
Managing keys from the terminal (recommended)
No manual file editing needed — keys are managed with the key subcommand:
llm-usage-meter key set anthropic # prompts for the key with hidden input
llm-usage-meter key set openrouter # (nothing echoes to screen or shell history)
llm-usage-meter key list # show configured keys, masked: sk-ant…6789
llm-usage-meter key delete anthropic # remove a stored key
Keys are written to ~/.config/llm-usage-meter/config.toml, which is created with
chmod 600 (owner read/write only) automatically. Hidden input means the key
never appears in your terminal scrollback or ~/.bash_history. Keys in the
config file take priority over environment variables.
You can still edit the file by hand (llm-usage-meter --init writes a commented
template) — the subcommands and manual edits coexist fine.
Interactive dashboard (default)
Just run it — in a real terminal, llm-usage-meter opens a live interactive
dashboard (stdlib curses, still zero dependencies):
llm-usage-meter live dashboard · refreshed 3s ago · auto 60s
─────────────────────────────────────────────────────────────────
▸ ● Anthropic key: config (sk-ant…cdef)
Requests left / min 48 / 50 ████████████████░░ 96%
● OpenRouter key: env (sk-or-…9x2k)
Credits left $12.06 / $25.00 ████████░░░░░░░░░░ 48%
○ Groq no key — press a to add
─────────────────────────────────────────────────────────────────
↑↓ select a add/edit key d delete key r refresh q quit
Only providers with a configured key appear on the dashboard — it stays
clean no matter how many providers llm-usage-meter supports. First launch with no
keys shows a friendly empty state pointing you at a.
- ↑/↓ (or j/k) select a provider
- a — open the Add-provider picker (lists only providers you haven't configured), then paste the key (masked input, saved to the 600-permission config, fetches immediately)
- e or Enter — edit the selected provider's key
- d — delete the stored key; the provider disappears from the dashboard (with y/N confirmation)
- r — refresh all; auto-refreshes every 60 s
- q — quit
Fetches run in background threads, so the UI never freezes.
Works on Linux, macOS, and Windows — installing from pip pulls in the small
windows-curses shim automatically on Windows only.
Non-interactive contexts (pipes, scripts, cron) automatically get the
classic one-shot output; force it anytime with llm-usage-meter --once.
Use
llm-usage-meter --once # one-shot report (skip the dashboard)
llm-usage-meter -p anthropic # one provider only
llm-usage-meter -w 60 # live dashboard, refresh every 60s
llm-usage-meter --json # for scripts / status bars
llm-usage-meter --demo # sample output, no network
Exit code is non-zero if any provider errored — handy for cron alerts:
llm-usage-meter --json || notify-send "LLM quota check failed"
Why some providers show different things
There is no universal "credits left" API. Each provider exposes something different, and llm-usage-meter shows the best available truth for each:
- Prepaid balance (OpenRouter, DeepSeek): a real dollar number remaining.
- Rate limits (Anthropic): pay-as-you-go has no "balance", so the
meaningful quota is your per-minute request/token allowance, read from
response headers on a free
count_tokenscall. - Spend so far (OpenAI): OpenAI exposes cost history, not a balance; llm-usage-meter shows month-to-date spend so you can compare against your budget.
Add your own provider
Subclass Provider in llm_usage_meter/providers.py:
class MyProvider(Provider):
name = "MyProvider"
env_key = "MYPROVIDER_API_KEY"
config_section = "myprovider"
def fetch(self, key):
status, headers, data = _request(
"https://api.myprovider.com/v1/balance",
headers={"Authorization": f"Bearer {key}"},
)
if status != 200:
return QuotaResult(self.name, error=_api_err(status, data))
return QuotaResult(self.name, ok=True,
rows=[("Balance", _fmt_money(data["balance"]))])
Then add MyProvider() to the PROVIDERS list. Done.
License
MIT
Metadata
Release files for llm-usage-meter 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llm_usage_meter-0.1.1.tar.gz | 22.8 kB | Without provenance | Details for llm_usage_meter-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llm_usage_meter-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for llm_usage_meter-0.1.1-py3-none-any.whl |
Total release size: 43.1 kB
Release files / llm_usage_meter-0.1.1.tar.gz
| Download URL | llm_usage_meter-0.1.1.tar.gz |
|---|---|
| Size | 22.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5766c6543339b5e76b3d3274462fe0619778bf2dd615047af2902d3271d48a9a
|
|
BLAKE2b-256 checksum How to use checksums |
5bc056a21e9e4bfda281110c2979bb4892dff2efa84b2ad3225afddeb0050187
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.1
|
Release files / llm_usage_meter-0.1.1-py3-none-any.whl
| Download URL | llm_usage_meter-0.1.1-py3-none-any.whl |
|---|---|
| Size | 20.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2060b5f8c4a511a78e8bab0d8d9f0d21e500b910d9950730d9af9fcc4cee245c
|
|
BLAKE2b-256 checksum How to use checksums |
66bd307cb6277af07f834fcc32329b12a3d3a6939e11ea13e3c6548d98c9809a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.1
|
Security for llm-usage-meter 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.