llm-usage-meter 0.1.0

Lightweight terminal tool to check remaining credits / quota across LLM providers. Zero dependencies.

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-curses shim for the dashboard.
• Never costs credits. Only free endpoints are used: billing/balance APIs, the free count_tokens probe, 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_tokens call.
• 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