keymeter 0.1.0__tar.gz

keymeter-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# secrets
+.env
+.env.*
+!.env.example
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# poll logs written with --log
+*.csv
+
+# editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

keymeter-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-10-07)
+
+First public release.
+
+- `keymeter web`: browser dashboard with spend vs. budget, burn rate, run-out time, projected spend at
+  reset, spend-over-time charts, spend per model, limits, an event log, and optional sound and desktop
+  alerts. Listens on localhost only unless `--host` says otherwise.
+- `keymeter tui`: the same numbers as a live terminal dashboard, plus the team's budget and keys on
+  LiteLLM when the key may read them.
+- `keymeter json`: one snapshot as JSON, exit code 1 when the key is not usable.
+- Gateways: LiteLLM proxy (`/key/info`) and OpenRouter (`/api/v1/key`), picked automatically from the
+  URL or the key.

keymeter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Do Pham Bao Hoang
+
+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.

keymeter-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: keymeter
+Version: 0.1.0
+Summary: Live spend, budget and burn-rate dashboard for one LiteLLM or OpenRouter API key, in the browser or the terminal.
+Project-URL: Homepage, https://github.com/hoanghero125/keymeter
+Project-URL: Issues, https://github.com/hoanghero125/keymeter/issues
+Project-URL: Changelog, https://github.com/hoanghero125/keymeter/blob/main/CHANGELOG.md
+Author: Do Pham Bao Hoang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-key,budget,dashboard,litellm,llm,monitoring,openrouter,quota,spend
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# keymeter
+
+[![CI](https://github.com/hoanghero125/keymeter/actions/workflows/ci.yml/badge.svg)](https://github.com/hoanghero125/keymeter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/keymeter)](https://pypi.org/project/keymeter/)
+
+A live dashboard for one LLM gateway API key: how much of its budget is spent, how fast it is going,
+and when it will run out. It works with a [LiteLLM](https://github.com/BerriAI/litellm) proxy or
+[OpenRouter](https://openrouter.ai), in the browser or in the terminal.
+
+![keymeter in the browser](https://raw.githubusercontent.com/hoanghero125/keymeter/main/docs/screenshot.png)
+
+LiteLLM's admin UI needs an admin key. keymeter only needs the key you were handed, which is often all
+you have: a team key at work, a key for a hackathon or a course. It polls the gateway's read-only key
+endpoint (no tokens spent) and shows:
+
+- spend vs. budget, what is left, and when the budget resets
+- the burn rate over the last 15 minutes, when the budget runs out at that rate, and the projected
+  spend at reset
+- charts of spend over time and spend per interval, with a table view
+- spend per model and per-model budgets, rate limits, allowed models, expiry and blocked state (LiteLLM)
+- an event log, and optional sound and desktop alerts when the status changes or a budget passes 80%
+  or 95%
+
+The key stays in the keymeter process. The browser only ever sees a masked version of it.
+
+## Install
+
+```bash
+pipx install keymeter        # or: uv tool install keymeter
+```
+
+keymeter needs Python 3.10 or newer.
+
+## Quick start
+
+**LiteLLM proxy**
+
+```bash
+export KEYMETER_URL=https://llm.example.com    # your proxy
+export KEYMETER_KEY=sk-...
+keymeter web
+```
+
+**OpenRouter**
+
+```bash
+export KEYMETER_KEY=sk-or-v1-...
+keymeter web
+```
+
+Then open <http://localhost:8765>. keymeter recognises OpenRouter from the `sk-or-` key or an
+`openrouter.ai` URL, so it needs no URL there.
+
+On Windows PowerShell, set the variables with `$env:KEYMETER_KEY = "sk-..."`. You can also put
+them in a `.env` file instead (see [Configuration](#configuration)).
+
+## Commands
+
+| Command | |
+|---|---|
+| `keymeter web` | browser dashboard on <http://localhost:8765> |
+| `keymeter tui` | live dashboard in the terminal; on LiteLLM it also shows the team's budget and keys when the key may read them |
+| `keymeter tui --once` | print one snapshot and exit |
+| `keymeter json` | print one snapshot as JSON and exit with code 1 when the key is not usable, for scripts and cron jobs |
+
+Options (`keymeter COMMAND -h` lists them per command):
+
+| Option | Default | |
+|---|---|---|
+| `--gateway` | `auto` | `litellm`, `openrouter`, or `auto` to pick from the URL and key |
+| `--url` | depends on the gateway | gateway base URL; `http://localhost:4000` for LiteLLM, `https://openrouter.ai/api` for OpenRouter. A trailing `/v1` is fine. |
+| `--env FILE` | `.env` | where to read settings from |
+| `-i`, `--interval` | `15` | seconds between polls (`web`, `tui`) |
+| `--window` | `15` | burn-rate window in minutes (`web`, `tui`) |
+| `--warn` / `--crit` | `0.8` / `0.95` | alert thresholds, as a fraction of a budget (`web`, `tui`) |
+| `--log FILE.csv` | | also append every poll to a CSV file (`web`, `tui`) |
+| `--host` / `--port` | `127.0.0.1` / `8765` | where the dashboard listens (`web`) |
+| `--no-team` | | skip LiteLLM's `/team/info` (`tui`, `json`) |
+| `--no-bell` | | don't beep on alerts (`tui`) |
+
+## Configuration
+
+keymeter reads three settings, from the environment first and then from a `.env` file in the
+current directory (or the file given with `--env`):
+
+| Variable | |
+|---|---|
+| `KEYMETER_KEY` | the API key to watch (required) |
+| `KEYMETER_URL` | gateway base URL |
+| `KEYMETER_GATEWAY` | `auto`, `litellm` or `openrouter` |
+
+Copy [`.env.example`](.env.example) to `.env` to start. There is no `--key` option, because a key
+typed on the command line ends up in your shell history.
+
+When `KEYMETER_KEY` is already set in the environment, keymeter ignores `./.env` (but still reads a
+file you name with `--env`). That way a `.env` in whatever directory you happen to be in, such as a
+cloned repository, can't send your key to another server.
+
+## What each gateway reports
+
+| | LiteLLM | OpenRouter |
+|---|---|---|
+| Spend, budget, reset time, burn rate, projections | yes | yes |
+| Key expiry | yes | yes |
+| Spend per model, per-model budgets | yes | no |
+| Rate limits, allowed models, blocked state | yes | no |
+| Team budget and team keys (`tui`, `json`) | yes | no |
+
+On OpenRouter the budget is the key's credit limit. The spend shown is what counts against that limit
+in the current period. Limits reset at 00:00 UTC: daily, weekly on Monday, or on the 1st of the month.
+A key without a limit shows its all-time usage and no budget.
+
+## Running it on a server
+
+`keymeter web` listens on `127.0.0.1` only. To watch it from your laptop, forward the port over SSH:
+
+```bash
+# on the server
+keymeter web
+
+# on your laptop
+ssh -N -L 8765:localhost:8765 you@server
+```
+
+Then open <http://localhost:8765> on the laptop. Because the browser sees `localhost`, desktop
+notifications work as well (browsers only allow them over HTTPS or on localhost).
+
+On `127.0.0.1`, keymeter answers only requests addressed to `localhost`, so other websites can't read
+it through DNS rebinding. A reverse proxy in front of it has to send `Host: localhost`.
+
+To keep it running after you log out, use `tmux`, a systemd service, or
+`nohup keymeter web > keymeter.log 2>&1 &`.
+
+`keymeter web --host 0.0.0.0` serves the dashboard on every interface instead. There is no login,
+so anyone who can reach the port can see the key's spend, budget and model usage (not the key
+itself) and press "Poll now". If you do this, allow only your own IP in the firewall.
+
+## How it works
+
+- keymeter calls `GET /key/info` on LiteLLM (plus `/team/info` for `tui` and `json`), or
+  `GET /api/v1/key` on OpenRouter. These endpoints are read-only and cost nothing.
+- The burn rate is the spend added over the burn-rate window, per hour. When spend goes down,
+  keymeter takes it as a budget reset and starts measuring again.
+- When the gateway stops answering, polls back off to at most once a minute. The dashboard keeps
+  showing the last numbers it got and says how old they are.
+- The charts' history lives in memory for 24 hours and starts over when keymeter restarts. Use
+  `--log` to keep a permanent record.
+- The bell button in the browser turns on alerts: a short sound, plus a desktop notification when
+  the browser allows it.
+- The web UI fades things in and out as they change, and keeps still if your system asks for reduced
+  motion.
+
+## Development
+
+```bash
+git clone https://github.com/hoanghero125/keymeter
+cd keymeter
+uv sync
+uv run pytest
+uv run ruff check
+```
+
+Without uv, run `python -m venv .venv`, activate it, then `pip install -e . --group dev` (pip 25.1
+or newer).
+
+The web UI is plain HTML, CSS and JavaScript in `src/keymeter/static`, with no build step.
+
+To support another gateway, add an adapter in `src/keymeter/gateways/`. It fetches the key's data
+and translates it into the field names the rest of keymeter uses (LiteLLM's); see `openrouter.py`
+for a small example.
+
+### Releasing
+
+1. Set `__version__` in `src/keymeter/__init__.py` and add the release to `CHANGELOG.md`.
+2. Commit, then tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
+
+The `Release` workflow tests and builds the package, then publishes it to PyPI. Before the first
+release, set up trusted publishing once:
+
+- On PyPI, under *Your account → Publishing*, add a pending publisher with project `keymeter`,
+  owner `hoanghero125`, repository `keymeter`, workflow `release.yml` and environment `pypi`.
+- On GitHub, under *Settings → Environments*, create an environment named `pypi`.
+
+## License
+
+[MIT](LICENSE). keymeter is not affiliated with LiteLLM (BerriAI) or OpenRouter.

keymeter-0.1.0/README.md

@@ -0,0 +1,186 @@
+# keymeter
+
+[![CI](https://github.com/hoanghero125/keymeter/actions/workflows/ci.yml/badge.svg)](https://github.com/hoanghero125/keymeter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/keymeter)](https://pypi.org/project/keymeter/)
+
+A live dashboard for one LLM gateway API key: how much of its budget is spent, how fast it is going,
+and when it will run out. It works with a [LiteLLM](https://github.com/BerriAI/litellm) proxy or
+[OpenRouter](https://openrouter.ai), in the browser or in the terminal.
+
+![keymeter in the browser](https://raw.githubusercontent.com/hoanghero125/keymeter/main/docs/screenshot.png)
+
+LiteLLM's admin UI needs an admin key. keymeter only needs the key you were handed, which is often all
+you have: a team key at work, a key for a hackathon or a course. It polls the gateway's read-only key
+endpoint (no tokens spent) and shows:
+
+- spend vs. budget, what is left, and when the budget resets
+- the burn rate over the last 15 minutes, when the budget runs out at that rate, and the projected
+  spend at reset
+- charts of spend over time and spend per interval, with a table view
+- spend per model and per-model budgets, rate limits, allowed models, expiry and blocked state (LiteLLM)
+- an event log, and optional sound and desktop alerts when the status changes or a budget passes 80%
+  or 95%
+
+The key stays in the keymeter process. The browser only ever sees a masked version of it.
+
+## Install
+
+```bash
+pipx install keymeter        # or: uv tool install keymeter
+```
+
+keymeter needs Python 3.10 or newer.
+
+## Quick start
+
+**LiteLLM proxy**
+
+```bash
+export KEYMETER_URL=https://llm.example.com    # your proxy
+export KEYMETER_KEY=sk-...
+keymeter web
+```
+
+**OpenRouter**
+
+```bash
+export KEYMETER_KEY=sk-or-v1-...
+keymeter web
+```
+
+Then open <http://localhost:8765>. keymeter recognises OpenRouter from the `sk-or-` key or an
+`openrouter.ai` URL, so it needs no URL there.
+
+On Windows PowerShell, set the variables with `$env:KEYMETER_KEY = "sk-..."`. You can also put
+them in a `.env` file instead (see [Configuration](#configuration)).
+
+## Commands
+
+| Command | |
+|---|---|
+| `keymeter web` | browser dashboard on <http://localhost:8765> |
+| `keymeter tui` | live dashboard in the terminal; on LiteLLM it also shows the team's budget and keys when the key may read them |
+| `keymeter tui --once` | print one snapshot and exit |
+| `keymeter json` | print one snapshot as JSON and exit with code 1 when the key is not usable, for scripts and cron jobs |
+
+Options (`keymeter COMMAND -h` lists them per command):
+
+| Option | Default | |
+|---|---|---|
+| `--gateway` | `auto` | `litellm`, `openrouter`, or `auto` to pick from the URL and key |
+| `--url` | depends on the gateway | gateway base URL; `http://localhost:4000` for LiteLLM, `https://openrouter.ai/api` for OpenRouter. A trailing `/v1` is fine. |
+| `--env FILE` | `.env` | where to read settings from |
+| `-i`, `--interval` | `15` | seconds between polls (`web`, `tui`) |
+| `--window` | `15` | burn-rate window in minutes (`web`, `tui`) |
+| `--warn` / `--crit` | `0.8` / `0.95` | alert thresholds, as a fraction of a budget (`web`, `tui`) |
+| `--log FILE.csv` | | also append every poll to a CSV file (`web`, `tui`) |
+| `--host` / `--port` | `127.0.0.1` / `8765` | where the dashboard listens (`web`) |
+| `--no-team` | | skip LiteLLM's `/team/info` (`tui`, `json`) |
+| `--no-bell` | | don't beep on alerts (`tui`) |
+
+## Configuration
+
+keymeter reads three settings, from the environment first and then from a `.env` file in the
+current directory (or the file given with `--env`):
+
+| Variable | |
+|---|---|
+| `KEYMETER_KEY` | the API key to watch (required) |
+| `KEYMETER_URL` | gateway base URL |
+| `KEYMETER_GATEWAY` | `auto`, `litellm` or `openrouter` |
+
+Copy [`.env.example`](.env.example) to `.env` to start. There is no `--key` option, because a key
+typed on the command line ends up in your shell history.
+
+When `KEYMETER_KEY` is already set in the environment, keymeter ignores `./.env` (but still reads a
+file you name with `--env`). That way a `.env` in whatever directory you happen to be in, such as a
+cloned repository, can't send your key to another server.
+
+## What each gateway reports
+
+| | LiteLLM | OpenRouter |
+|---|---|---|
+| Spend, budget, reset time, burn rate, projections | yes | yes |
+| Key expiry | yes | yes |
+| Spend per model, per-model budgets | yes | no |
+| Rate limits, allowed models, blocked state | yes | no |
+| Team budget and team keys (`tui`, `json`) | yes | no |
+
+On OpenRouter the budget is the key's credit limit. The spend shown is what counts against that limit
+in the current period. Limits reset at 00:00 UTC: daily, weekly on Monday, or on the 1st of the month.
+A key without a limit shows its all-time usage and no budget.
+
+## Running it on a server
+
+`keymeter web` listens on `127.0.0.1` only. To watch it from your laptop, forward the port over SSH:
+
+```bash
+# on the server
+keymeter web
+
+# on your laptop
+ssh -N -L 8765:localhost:8765 you@server
+```
+
+Then open <http://localhost:8765> on the laptop. Because the browser sees `localhost`, desktop
+notifications work as well (browsers only allow them over HTTPS or on localhost).
+
+On `127.0.0.1`, keymeter answers only requests addressed to `localhost`, so other websites can't read
+it through DNS rebinding. A reverse proxy in front of it has to send `Host: localhost`.
+
+To keep it running after you log out, use `tmux`, a systemd service, or
+`nohup keymeter web > keymeter.log 2>&1 &`.
+
+`keymeter web --host 0.0.0.0` serves the dashboard on every interface instead. There is no login,
+so anyone who can reach the port can see the key's spend, budget and model usage (not the key
+itself) and press "Poll now". If you do this, allow only your own IP in the firewall.
+
+## How it works
+
+- keymeter calls `GET /key/info` on LiteLLM (plus `/team/info` for `tui` and `json`), or
+  `GET /api/v1/key` on OpenRouter. These endpoints are read-only and cost nothing.
+- The burn rate is the spend added over the burn-rate window, per hour. When spend goes down,
+  keymeter takes it as a budget reset and starts measuring again.
+- When the gateway stops answering, polls back off to at most once a minute. The dashboard keeps
+  showing the last numbers it got and says how old they are.
+- The charts' history lives in memory for 24 hours and starts over when keymeter restarts. Use
+  `--log` to keep a permanent record.
+- The bell button in the browser turns on alerts: a short sound, plus a desktop notification when
+  the browser allows it.
+- The web UI fades things in and out as they change, and keeps still if your system asks for reduced
+  motion.
+
+## Development
+
+```bash
+git clone https://github.com/hoanghero125/keymeter
+cd keymeter
+uv sync
+uv run pytest
+uv run ruff check
+```
+
+Without uv, run `python -m venv .venv`, activate it, then `pip install -e . --group dev` (pip 25.1
+or newer).
+
+The web UI is plain HTML, CSS and JavaScript in `src/keymeter/static`, with no build step.
+
+To support another gateway, add an adapter in `src/keymeter/gateways/`. It fetches the key's data
+and translates it into the field names the rest of keymeter uses (LiteLLM's); see `openrouter.py`
+for a small example.
+
+### Releasing
+
+1. Set `__version__` in `src/keymeter/__init__.py` and add the release to `CHANGELOG.md`.
+2. Commit, then tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
+
+The `Release` workflow tests and builds the package, then publishes it to PyPI. Before the first
+release, set up trusted publishing once:
+
+- On PyPI, under *Your account → Publishing*, add a pending publisher with project `keymeter`,
+  owner `hoanghero125`, repository `keymeter`, workflow `release.yml` and environment `pypi`.
+- On GitHub, under *Settings → Environments*, create an environment named `pypi`.
+
+## License
+
+[MIT](LICENSE). keymeter is not affiliated with LiteLLM (BerriAI) or OpenRouter.

keymeter-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keymeter"
+dynamic = ["version"]
+description = "Live spend, budget and burn-rate dashboard for one LiteLLM or OpenRouter API key, in the browser or the terminal."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Do Pham Bao Hoang" }]
+requires-python = ">=3.10"
+dependencies = ["rich>=13"]
+keywords = ["litellm", "openrouter", "llm", "api-key", "budget", "quota", "spend", "dashboard", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Monitoring",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoanghero125/keymeter"
+Issues = "https://github.com/hoanghero125/keymeter/issues"
+Changelog = "https://github.com/hoanghero125/keymeter/blob/main/CHANGELOG.md"
+
+[project.scripts]
+keymeter = "keymeter.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.version]
+path = "src/keymeter/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 140
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = ["I", "B", "UP"]

keymeter-0.1.0/src/keymeter/__init__.py

@@ -0,0 +1,3 @@
+"""keymeter: live spend, budget and burn rate for one LiteLLM or OpenRouter API key."""
+
+__version__ = "0.1.0"

keymeter-0.1.0/src/keymeter/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from keymeter.cli import main
+
+sys.exit(main())

keymeter-0.1.0/src/keymeter/cli.py

@@ -0,0 +1,114 @@
+"""Command line: `keymeter web`, `keymeter tui` and `keymeter json`.
+
+Settings come from the environment, then from a .env file (the current directory's, or --env FILE):
+  KEYMETER_KEY      the API key to watch (required)
+  KEYMETER_URL      gateway base URL (default depends on the gateway)
+  KEYMETER_GATEWAY  auto, litellm or openrouter (default auto)
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from keymeter import __version__, gateways
+from keymeter.monitor import Monitor
+from keymeter.util import tidy
+
+
+def load_env(path, required):
+    """Minimal .env reader (KEY=VALUE lines); real environment variables win."""
+    if not path.is_file():
+        if required:
+            sys.exit(f"--env file not found: {path}")
+        return
+    raw = path.read_bytes()
+    try:
+        text = raw.decode("utf-16") if raw[:2] in (b"\xff\xfe", b"\xfe\xff") else raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        sys.exit(f"can't read {path}: save it as UTF-8")
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+def build_parser():
+    conn = argparse.ArgumentParser(add_help=False)
+    g = conn.add_argument_group("gateway")
+    g.add_argument("--gateway", choices=["auto", *gateways.GATEWAYS],
+                   help="gateway type (default: $KEYMETER_GATEWAY or auto: openrouter for openrouter.ai URLs "
+                        "and sk-or- keys, litellm otherwise)")
+    g.add_argument("--url", help="gateway base URL (default: $KEYMETER_URL, else http://localhost:4000 for "
+                                 "litellm or https://openrouter.ai/api for openrouter)")
+    g.add_argument("--env", metavar="FILE", help="read settings from this file (default: .env in the current directory)")
+
+    watch = argparse.ArgumentParser(add_help=False)
+    w = watch.add_argument_group("monitoring")
+    w.add_argument("-i", "--interval", type=float, default=15, help="seconds between polls (default 15)")
+    w.add_argument("--window", type=float, default=15, help="burn-rate window in minutes (default 15)")
+    w.add_argument("--warn", type=float, default=0.8, help="warn at this fraction of a budget (default 0.8)")
+    w.add_argument("--crit", type=float, default=0.95, help="critical at this fraction (default 0.95)")
+    w.add_argument("--log", metavar="CSV", help="also append every poll to this CSV file")
+
+    p = argparse.ArgumentParser(
+        prog="keymeter",
+        description="Live spend, budget and burn rate for one LiteLLM or OpenRouter API key.",
+        epilog="The key is read from KEYMETER_KEY (environment or .env). Run `keymeter COMMAND -h` for a command's options.")
+    p.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    web = sub.add_parser("web", parents=[conn, watch], help="browser dashboard",
+                         description="Serve a live dashboard for the key in the browser.")
+    web.add_argument("--host", default="127.0.0.1",
+                     help="address to listen on (default 127.0.0.1, this machine only; 0.0.0.0 = all interfaces, no login)")
+    web.add_argument("--port", type=int, default=8765, help="port (default 8765)")
+
+    tui = sub.add_parser("tui", parents=[conn, watch], help="terminal dashboard",
+                         description="Show a live dashboard for the key in the terminal.")
+    tui.add_argument("--once", action="store_true", help="print one snapshot and exit (exit 1 if not OK)")
+    tui.add_argument("--no-team", action="store_true", help="don't query the team (LiteLLM /team/info)")
+    tui.add_argument("--no-bell", action="store_true", help="don't beep on alerts")
+
+    js = sub.add_parser("json", parents=[conn], help="print one snapshot as JSON and exit",
+                        description="Poll once and print the summary as JSON. Exits 1 if the status is not OK.")
+    js.add_argument("--no-team", action="store_true", help="don't query the team (LiteLLM /team/info)")
+    js.set_defaults(interval=15, window=15, warn=0.8, crit=0.95, log=None)
+    return p
+
+
+def main(argv=None):
+    # write UTF-8 even when output goes to a pipe or file on Windows (Python's default from 3.15 on, PEP 686)
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    args = build_parser().parse_args(argv)
+    args.interval = max(args.interval, 1)
+    if args.env:
+        load_env(Path(args.env), required=True)
+    elif not os.environ.get("KEYMETER_KEY"):
+        # ./.env is only a fallback for the key itself: a .env in whatever directory you are in (a cloned
+        # repo, say) must not point a key from your environment at another server
+        load_env(Path(".env"), required=False)
+    key = os.environ.get("KEYMETER_KEY", "").strip().strip('"')
+    if not key:
+        sys.exit("KEYMETER_KEY is not set. Put it in a .env file in this directory, pass --env FILE, or export it.")
+    name = (args.gateway or os.environ.get("KEYMETER_GATEWAY") or "auto").strip().lower()
+    team = args.command != "web" and not args.no_team  # the web dashboard covers the key only
+    try:
+        gw = gateways.create(name, args.url or os.environ.get("KEYMETER_URL"), key, team=team)
+    except ValueError as e:
+        sys.exit(str(e))
+    mon = Monitor(gw, args)
+
+    if args.command == "json":
+        mon.poll()
+        print(json.dumps(tidy(mon.summary()), indent=2, ensure_ascii=False))
+        return 0 if mon.snap.status == "OK" else 1
+    if args.command == "web":
+        from keymeter import web
+        return web.serve(mon, args)
+    from keymeter import tui
+    return tui.run(mon, args)