Metadata-Version: 2.1
Name: llm-usage-meter
Version: 0.1.1
Summary: Lightweight terminal tool to check remaining credits / quota across LLM providers. Zero dependencies.
Author: Nidesh Pandey
License: MIT License
        
        Copyright (c) 2026 Nidesh Pandey
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nideshpandey/llm-usage-meter
Project-URL: Issues, https://github.com/nideshpandey/llm-usage-meter/issues
Keywords: llm,quota,credits,usage,cli,openai,anthropic,openrouter,deepseek
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: windows-curses; sys_platform == "win32"

# 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:

```bash
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:

```bash
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

```bash
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:

```bash
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`:

```python
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
