cursor-usage 0.1.0__py3-none-any.whl

cursor_usage/__init__.py

@@ -0,0 +1,3 @@
+"""cursor-usage: read your Cursor (cursor.com) usage, spend, and per-event logs."""
+
+__version__ = "0.1.0"

cursor_usage/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cursor_usage/api.py

@@ -0,0 +1,97 @@
+"""Minimal client for the Cursor dashboard usage API (stdlib only).
+
+Endpoints used (all on ``https://cursor.com``):
+  GET  /api/auth/me                                  -> {email, id, sub, ...}
+  GET  /api/usage?user=<id>                          -> legacy counter + startOfMonth
+  POST /api/dashboard/get-aggregated-usage-events    -> per-model tokens + cents
+  POST /api/dashboard/get-filtered-usage-events       -> per-event log (paginated)
+
+State-changing POSTs require an ``Origin: https://cursor.com`` header (CSRF guard).
+Auth is the ``WorkosCursorSessionToken`` cookie, value ``<sub>::<jwt>`` (the ``::``
+is sent URL-encoded as ``%3A%3A``).
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+from . import __version__
+
+BASE = "https://cursor.com"
+USER_AGENT = "cursor-usage/%s" % __version__
+
+
+class CursorAPIError(RuntimeError):
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        super().__init__("HTTP %s: %s" % (status, body[:300]))
+
+
+class CursorClient:
+    def __init__(self, cookie_value, timeout=30):
+        self._cookie = "WorkosCursorSessionToken=" + cookie_value.replace("::", "%3A%3A")
+        self._timeout = timeout
+
+    def _request(self, path, method="GET", body=None):
+        headers = {
+            "Cookie": self._cookie,
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+            headers["Origin"] = BASE  # required: dashboard CSRF check
+        req = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8", "ignore")
+        except urllib.error.HTTPError as exc:
+            raise CursorAPIError(exc.code, exc.read().decode("utf-8", "ignore"))
+        return json.loads(raw) if raw else {}
+
+    # -- endpoints ---------------------------------------------------------
+    def me(self):
+        return self._request("/api/auth/me")
+
+    def usage(self, user_id):
+        return self._request("/api/usage?user=%s" % user_id)
+
+    def aggregated_usage(self, user_id, start_ms, end_ms):
+        return self._request(
+            "/api/dashboard/get-aggregated-usage-events", "POST",
+            {"teamId": 0, "startDate": str(start_ms), "endDate": str(end_ms),
+             "userId": user_id},
+        )
+
+    def _events_page(self, user_id, start_ms, end_ms, page, page_size):
+        return self._request(
+            "/api/dashboard/get-filtered-usage-events", "POST",
+            {"teamId": 0, "startDate": str(start_ms), "endDate": str(end_ms),
+             "userId": user_id, "page": page, "pageSize": page_size},
+        )
+
+    def all_events(self, user_id, start_ms, end_ms, page_size=1000, progress=None):
+        """Fetch every usage event in the window by paginating.
+
+        Returns ``(events, total_reported)``. ``progress(fetched, total)`` is
+        called after each page if provided.
+        """
+        first = self._events_page(user_id, start_ms, end_ms, 1, page_size)
+        total = int(first.get("totalUsageEventsCount", 0) or 0)
+        events = list(first.get("usageEventsDisplay", []))
+        if progress:
+            progress(len(events), total)
+        page = 2
+        while len(events) < total and page <= 1000:  # 1000-page safety cap
+            chunk = self._events_page(user_id, start_ms, end_ms, page, page_size)
+            rows = chunk.get("usageEventsDisplay", [])
+            if not rows:
+                break
+            events.extend(rows)
+            if progress:
+                progress(len(events), total)
+            page += 1
+        return events, total

cursor_usage/auth.py

@@ -0,0 +1,194 @@
+"""Cross-platform resolution of the Cursor web session token.
+
+Why this exists
+---------------
+A personal Cursor API key (``crsr_...``) only reaches the Agent API
+(``api.cursor.com/v1/*``). It CANNOT read usage/spend -- those endpoints reject
+it with "Invalid Team API Key". The data the web dashboard shows comes from
+``cursor.com/api/*`` and is gated by a WorkOS *session* cookie
+(``WorkosCursorSessionToken``), not the API key.
+
+The Cursor app/CLI stores that session JWT locally. We read it from whichever of
+these is available, in priority order (all are local-only; nothing is sent
+anywhere except cursor.com):
+
+1. ``$CURSOR_SESSION_TOKEN`` -- explicit override (raw JWT, or full ``sub::jwt``).
+2. macOS Keychain service ``cursor-access-token`` (used by ``cursor-agent``).
+3. OS keyring via the optional ``keyring`` package (Linux Secret Service /
+   Windows Credential Locker / macOS Keychain).
+4. The Cursor IDE SQLite state DB (``state.vscdb`` -> ``cursorAuth/accessToken``),
+   whose layout is identical on macOS, Linux and Windows.
+
+The dashboard cookie value is ``<workos_sub>::<jwt>``; ``sub`` is the ``sub``
+claim of the JWT, so we can derive the whole cookie from just the token.
+"""
+
+import base64
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+from pathlib import Path
+
+KEYCHAIN_SERVICE = "cursor-access-token"
+KEYCHAIN_ACCOUNT = "cursor-user"
+
+
+class SessionNotFound(RuntimeError):
+    """Raised when no Cursor session token can be located."""
+
+
+def _jwt_claims(token):
+    """Decode a JWT payload to a dict, or ``{}`` if it can't be parsed."""
+    try:
+        payload = token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)  # restore base64url padding
+        return json.loads(base64.urlsafe_b64decode(payload))
+    except Exception:
+        return {}
+
+
+def _cookie_id(claims):
+    """Return the cookie id from a token's ``sub`` claim, or ``None``.
+
+    WorkOS subjects look like ``<connection>|<user_id>`` (e.g.
+    ``github|user_01ABC...``). The dashboard cookie wants the bare ``user_...``
+    part (what ``/api/auth/me`` reports as ``sub``), so strip any connection
+    prefix before the last ``|``.
+    """
+    sub = claims.get("sub")
+    return sub.split("|")[-1] if sub else None
+
+
+def _from_env():
+    return os.environ.get("CURSOR_SESSION_TOKEN")
+
+
+def _from_macos_keychain():
+    if sys.platform != "darwin":
+        return None
+    try:
+        out = subprocess.run(
+            ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"],
+            capture_output=True, text=True, timeout=15,
+        )
+        return out.stdout.strip() or None
+    except Exception:
+        return None
+
+
+def _from_keyring():
+    try:
+        import keyring  # optional dependency
+    except Exception:
+        return None
+    try:
+        return keyring.get_password(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT)
+    except Exception:
+        return None
+
+
+def _state_db_candidates():
+    """Yield possible Cursor IDE ``state.vscdb`` paths for the current OS."""
+    home = Path.home()
+    if sys.platform == "darwin":
+        base = home / "Library" / "Application Support"
+    elif sys.platform.startswith("win"):
+        base = Path(os.environ.get("APPDATA", home / "AppData" / "Roaming"))
+    else:  # linux / other unix
+        base = Path(os.environ.get("XDG_CONFIG_HOME", home / ".config"))
+    for app in ("Cursor", "Cursor Nightly"):
+        yield base / app / "User" / "globalStorage" / "state.vscdb"
+
+
+def _from_state_db():
+    for path in _state_db_candidates():
+        if not path.exists():
+            continue
+        try:
+            con = sqlite3.connect("file:%s?mode=ro" % path, uri=True)
+            try:
+                row = con.execute(
+                    "SELECT value FROM ItemTable WHERE key = ?",
+                    ("cursorAuth/accessToken",),
+                ).fetchone()
+            finally:
+                con.close()
+        except Exception:
+            continue
+        if row and row[0]:
+            value = row[0]
+            if isinstance(value, bytes):
+                value = value.decode("utf-8", "ignore")
+            return value.strip().strip('"')
+    return None
+
+
+# Local credential stores, tried in order (env override is handled separately).
+_LOCAL_SOURCES = (
+    ("macOS keychain", _from_macos_keychain),
+    ("OS keyring", _from_keyring),
+    ("Cursor state DB", _from_state_db),
+)
+
+
+def _log(verbose, name):
+    if verbose:
+        print("[auth] using session from %s" % name, file=sys.stderr)
+
+
+def resolve_cookie_value(verbose=False):
+    """Return ``"<id>::<jwt>"`` suitable for the dashboard cookie.
+
+    Only a WorkOS *session* token authenticates the dashboard; an
+    ``api_key_token`` (which ``cursor-agent`` may store in the keychain) returns
+    HTTP 204 and is skipped. Raises :class:`SessionNotFound` if none is found.
+    """
+    # 1. Explicit override always wins (raw JWT, or full ``id::jwt`` cookie).
+    env = _from_env()
+    if env:
+        env = env.strip().replace("%3A%3A", "::")
+        if "::" in env:
+            _log(verbose, "$CURSOR_SESSION_TOKEN")
+            return env
+        cid = _cookie_id(_jwt_claims(env))
+        if cid:
+            _log(verbose, "$CURSOR_SESSION_TOKEN")
+            return "%s::%s" % (cid, env)
+
+    # 2. Local stores -- require a session token; skip api_key_token.
+    tried = ["$CURSOR_SESSION_TOKEN"]
+    saw_api_key = False
+    for name, source in _LOCAL_SOURCES:
+        tried.append(name)
+        token = source()
+        if not token:
+            continue
+        token = token.strip().replace("%3A%3A", "::")
+        if "::" in token:  # already a full "id::jwt" cookie value
+            _log(verbose, name)
+            return token
+        claims = _jwt_claims(token)
+        cid = _cookie_id(claims)
+        if not cid:
+            continue
+        if claims.get("type") == "api_key_token":
+            saw_api_key = True  # valid token, but not a *web* session
+            continue
+        _log(verbose, name)
+        return "%s::%s" % (cid, token)
+
+    hint = ""
+    if saw_api_key:
+        hint = ("\nNote: found an api_key_token (Agent API), but that does not "
+                "authenticate the\nusage dashboard. A *web session* is needed.")
+    raise SessionNotFound(
+        "Could not find a usable Cursor session token.\n"
+        "Tried: %s.%s\n\n"
+        "Fix one of:\n"
+        "  - Sign in via the Cursor app (this stores a web session), or\n"
+        "  - Set CURSOR_SESSION_TOKEN to your WorkosCursorSessionToken cookie\n"
+        "    (cursor.com -> DevTools -> Application -> Cookies)."
+        % (", ".join(tried), hint)
+    )

cursor_usage/cli.py

@@ -0,0 +1,127 @@
+"""Command-line entry point for cursor-usage."""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+
+from . import __version__
+from .api import CursorAPIError, CursorClient
+from .auth import SessionNotFound, resolve_cookie_value
+from .report import render_by_day, render_summary, write_csv
+
+
+def _ms(dt):
+    return int(dt.timestamp() * 1000)
+
+
+def _parse_date(s):
+    return datetime.strptime(s, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+
+
+def _resolve_window(args, client, user_id):
+    """Return (start_ms, end_ms, start_label, end_label)."""
+    now = datetime.now(timezone.utc)
+    end = _parse_date(args.end) + timedelta(days=1) if args.end else now
+    if args.start:
+        start = _parse_date(args.start)
+    elif args.days:
+        start = now - timedelta(days=args.days)
+    elif args.month:
+        y, m = (int(x) for x in args.month.split("-"))
+        start = datetime(y, m, 1, tzinfo=timezone.utc)
+        if not args.end:
+            nm = datetime(y + (m == 12), (m % 12) + 1, 1, tzinfo=timezone.utc)
+            end = min(now, nm)
+    else:
+        # default: current billing month, per /api/usage startOfMonth
+        som = client.usage(user_id).get("startOfMonth")
+        start = (datetime.fromisoformat(som.replace("Z", "+00:00"))
+                 if som else now.replace(day=1, hour=0, minute=0, second=0, microsecond=0))
+    return _ms(start), _ms(end), start.strftime("%Y-%m-%d"), end.strftime("%Y-%m-%d")
+
+
+def _progress(fetched, total):
+    if total:
+        sys.stderr.write("\r[events] %d/%d" % (fetched, total))
+        sys.stderr.flush()
+        if fetched >= total:
+            sys.stderr.write("\n")
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="cursor-usage",
+        description="Show Cursor (cursor.com) usage, spend and per-event logs "
+                    "for the locally signed-in account.",
+    )
+    p.add_argument("--by-day", action="store_true",
+                   help="break usage down by calendar day (fetches per-event data)")
+    p.add_argument("--csv", metavar="FILE",
+                   help="write the per-event log to FILE as CSV")
+    p.add_argument("--json", action="store_true",
+                   help="print the raw aggregated-usage JSON and exit")
+    g = p.add_argument_group("time window (default: current billing month)")
+    g.add_argument("--start", metavar="YYYY-MM-DD", help="window start (inclusive)")
+    g.add_argument("--end", metavar="YYYY-MM-DD", help="window end (inclusive)")
+    g.add_argument("--days", type=int, metavar="N", help="last N days")
+    g.add_argument("--month", metavar="YYYY-MM", help="a specific calendar month")
+    p.add_argument("--page-size", type=int, default=1000,
+                   help="events per API page when paginating (default: 1000)")
+    p.add_argument("-v", "--verbose", action="store_true", help="log the token source")
+    p.add_argument("-V", "--version", action="version",
+                   version="cursor-usage %s" % __version__)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        cookie = resolve_cookie_value(verbose=args.verbose)
+    except SessionNotFound as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    client = CursorClient(cookie)
+    try:
+        me = client.me()
+        user_id = me.get("id")
+        email = me.get("email", "unknown")
+        if not user_id:
+            print("Session token is invalid or expired (auth/me returned no id).\n"
+                  "Re-authenticate: cursor-agent login", file=sys.stderr)
+            return 2
+
+        start_ms, end_ms, start_label, end_label = _resolve_window(args, client, user_id)
+        meta = {"email": email, "start": start_label, "end": end_label}
+
+        if args.json:
+            print(json.dumps(client.aggregated_usage(user_id, start_ms, end_ms), indent=2))
+            return 0
+
+        # The aggregated endpoint powers the summary (one cheap call).
+        print(render_summary(client.aggregated_usage(user_id, start_ms, end_ms), meta))
+
+        # Per-event data powers --by-day and --csv; fetch it once if needed.
+        if args.by_day or args.csv:
+            events, total = client.all_events(
+                user_id, start_ms, end_ms, page_size=args.page_size, progress=_progress)
+            if args.by_day:
+                print()
+                print(render_by_day(events, meta))
+            if args.csv:
+                n = write_csv(events, args.csv)
+                print("\nWrote %d events to %s" % (n, args.csv))
+    except CursorAPIError as exc:
+        print("\nCursor API error (HTTP %s): %s" % (exc.status, exc.body[:300]), file=sys.stderr)
+        if exc.status in (401, 403):
+            print("Session may be expired. Re-authenticate: cursor-agent login", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print("\nNetwork error talking to cursor.com: %s" % exc, file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cursor_usage/report.py

@@ -0,0 +1,134 @@
+"""Turn raw API payloads into summaries, day breakdowns and CSV rows."""
+
+import csv
+from collections import OrderedDict
+from datetime import datetime, timezone
+
+
+# --- field extraction -----------------------------------------------------
+def _i(d, k):
+    try:
+        return int(d.get(k, 0) or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _f(d, k):
+    try:
+        return float(d.get(k, 0) or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def event_row(ev):
+    """Flatten one ``usageEventsDisplay`` entry into a plain dict."""
+    tu = ev.get("tokenUsage") or {}
+    ts_ms = _i(ev, "timestamp")
+    local = datetime.fromtimestamp(ts_ms / 1000).astimezone() if ts_ms else None
+    return OrderedDict([
+        ("datetime_local", local.isoformat() if local else ""),
+        ("timestamp_ms", ts_ms),
+        ("date", local.strftime("%Y-%m-%d") if local else ""),
+        ("model", ev.get("model", "")),
+        ("kind", ev.get("kind", "")),
+        ("input_tokens", _i(tu, "inputTokens")),
+        ("output_tokens", _i(tu, "outputTokens")),
+        ("cache_read_tokens", _i(tu, "cacheReadTokens")),
+        ("cache_write_tokens", _i(tu, "cacheWriteTokens")),
+        ("value_cents", round(_f(tu, "totalCents"), 6)),
+        ("charged_cents", round(_f(ev, "chargedCents"), 6)),
+        ("requests_costs", ev.get("requestsCosts", 0)),
+        ("is_headless", bool(ev.get("isHeadless", False))),
+        ("owning_user", ev.get("owningUser", "")),
+    ])
+
+
+# --- formatting helpers ---------------------------------------------------
+def _money(cents):
+    return "$%s" % format(cents / 100.0, ",.2f")
+
+
+def _n(x):
+    return format(int(x), ",")
+
+
+def _rule(width=78):
+    return "-" * width
+
+
+# --- summary (from aggregated endpoint) -----------------------------------
+def render_summary(agg, meta):
+    rows = agg.get("aggregations", []) or []
+    cents = lambda r: _f(r, "totalCents")
+    total = sum(cents(r) for r in rows)
+    ti = sum(_i(r, "inputTokens") for r in rows)
+    to = sum(_i(r, "outputTokens") for r in rows)
+    tcr = sum(_i(r, "cacheReadTokens") for r in rows)
+    tcw = sum(_i(r, "cacheWriteTokens") for r in rows)
+
+    out = ["=" * 78]
+    out.append("CURSOR USAGE  |  %s  |  %s -> %s"
+               % (meta["email"], meta["start"], meta["end"]))
+    out.append("=" * 78)
+    out.append("Included value used : %s   (compute consumed; included in plan)" % _money(total))
+    out.append("Tokens   in=%s  out=%s" % (_n(ti), _n(to)))
+    out.append("         cacheRead=%s  cacheWrite=%s" % (_n(tcr), _n(tcw)))
+    out.append(_rule())
+    out.append("%-36s%10s%14s%12s" % ("model", "$ value", "in tok", "out tok"))
+    out.append(_rule())
+    for r in sorted(rows, key=lambda x: -cents(x)):
+        out.append("%-36s%10s%14s%12s" % (
+            r.get("modelIntent", "?"),
+            format(cents(r) / 100.0, ",.2f"),
+            _n(_i(r, "inputTokens")),
+            _n(_i(r, "outputTokens")),
+        ))
+    return "\n".join(out)
+
+
+# --- per-day breakdown (from events) --------------------------------------
+def render_by_day(events, meta):
+    days = OrderedDict()
+    for ev in events:
+        row = event_row(ev)
+        d = row["date"] or "unknown"
+        b = days.setdefault(d, {"n": 0, "in": 0, "out": 0, "cents": 0.0})
+        b["n"] += 1
+        b["in"] += row["input_tokens"]
+        b["out"] += row["output_tokens"]
+        b["cents"] += row["value_cents"]
+
+    out = ["=" * 78]
+    out.append("CURSOR USAGE BY DAY  |  %s  |  %s -> %s"
+               % (meta["email"], meta["start"], meta["end"]))
+    out.append("=" * 78)
+    out.append("%-12s%9s%12s%15s%13s" % ("date", "events", "$ value", "in tok", "out tok"))
+    out.append(_rule())
+    tot = {"n": 0, "in": 0, "out": 0, "cents": 0.0}
+    for d in sorted(days):
+        b = days[d]
+        out.append("%-12s%9s%12s%15s%13s" % (
+            d, _n(b["n"]), format(b["cents"] / 100.0, ",.2f"), _n(b["in"]), _n(b["out"])))
+        for k in tot:
+            tot[k] += b[k]
+    out.append(_rule())
+    out.append("%-12s%9s%12s%15s%13s" % (
+        "TOTAL", _n(tot["n"]), format(tot["cents"] / 100.0, ",.2f"),
+        _n(tot["in"]), _n(tot["out"])))
+    return "\n".join(out)
+
+
+# --- CSV ------------------------------------------------------------------
+def write_csv(events, path):
+    rows = [event_row(e) for e in events]
+    rows.sort(key=lambda r: r["timestamp_ms"])
+    fields = list(event_row({}).keys())
+    with open(path, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=fields)
+        writer.writeheader()
+        writer.writerows(rows)
+    return len(rows)
+
+
+def to_iso(ms):
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d")

cursor_usage-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: cursor-usage
+Version: 0.1.0
+Summary: Cross-platform CLI to read your Cursor (cursor.com) usage, spend, and per-event logs.
+Author: cursor-usage contributors
+License: MIT
+Project-URL: Homepage, https://github.com/javaisbetterthanpython/cursor-usage
+Project-URL: Issues, https://github.com/javaisbetterthanpython/cursor-usage/issues
+Keywords: cursor,usage,spend,cli,ai,tokens,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: keyring
+Requires-Dist: keyring>=24; extra == "keyring"
+Dynamic: license-file
+
+<h1 align="center">📊 cursor-usage</h1>
+
+<p align="center">
+  <b>See your <a href="https://cursor.com">Cursor</a> usage, spend, and per-event logs — right from your terminal.</b>
+</p>
+
+<p align="center">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.8%2B-blue">
+  <img alt="Platforms" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey">
+  <img alt="Dependencies" src="https://img.shields.io/badge/dependencies-zero-brightgreen">
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green">
+</p>
+
+---
+
+Cursor shows your usage on its web dashboard, but there's no official way to get
+it from the command line. **`cursor-usage` gives you that** — a clean summary, a
+per-day breakdown, and a full per-event CSV export — using the session your
+Cursor app already has. No API key to manage, nothing to configure.
+
+```text
+==============================================================================
+CURSOR USAGE  |  you@example.com  |  2026-06-04 -> 2026-06-09
+==============================================================================
+Included value used : $875.81   (compute consumed; included in plan)
+Tokens   in=126,033,860  out=18,989,068
+         cacheRead=2,492,781,450  cacheWrite=8,322,520
+------------------------------------------------------------------------------
+model                                  $ value        in tok     out tok
+------------------------------------------------------------------------------
+composer-2.5                            460.14    95,638,983  13,315,470
+claude-4.6-opus-high                    233.71       786,434   1,059,451
+gemini-3.5-flash                         45.77    16,097,065   1,075,904
+gpt-5.4-high                             43.65     4,069,043   1,041,967
+...
+```
+
+## ✨ Features
+
+- **One command, real numbers** — per-model tokens and compute value for the
+  current billing month.
+- **📅 Per-day breakdown** — `--by-day` shows how much you burned each day.
+- **🧾 CSV export** — `--csv` dumps every usage event (timestamp, model, tokens,
+  cost) for your own spreadsheets and charts.
+- **🌍 Cross-platform** — macOS, Linux, and Windows.
+- **🔋 Zero dependencies** — pure Python standard library.
+- **🔒 Local & private** — reads the session your Cursor app already stored;
+  talks only to `cursor.com`. No telemetry, no third parties.
+
+## 🚀 Quickstart
+
+```bash
+pip install cursor-usage      # or: pip install . from a clone
+cursor-usage                      # summary for the current billing month
+```
+
+That's it — if you're signed in to Cursor on this machine, it just works.
+
+## 🧑‍💻 Usage
+
+| Command | What it does |
+|---|---|
+| `cursor-usage` | Summary for the current billing month |
+| `cursor-usage --by-day` | Add a per-day breakdown |
+| `cursor-usage --csv usage.csv` | Export every usage event to CSV |
+| `cursor-usage --days 7` | Window: the last 7 days |
+| `cursor-usage --month 2026-05` | Window: a specific month |
+| `cursor-usage --start 2026-06-01 --end 2026-06-07` | Window: an explicit range |
+| `cursor-usage --json` | Raw aggregated JSON (for scripting) |
+| `cursor-usage -v` | Also print which session source was used |
+
+Flags combine — e.g. `cursor-usage --by-day --csv june.csv --month 2026-06`.
+
+<details>
+<summary><b>📅 Example: <code>--by-day</code></b></summary>
+
+```text
+==============================================================================
+CURSOR USAGE BY DAY  |  you@example.com  |  2026-06-02 -> 2026-06-09
+==============================================================================
+date           events     $ value         in tok      out tok
+------------------------------------------------------------------------------
+2026-06-04        433      324.46     38,602,275    6,080,617
+2026-06-05        368      252.58     40,616,543    6,469,309
+2026-06-06        416      121.06     29,686,247    4,497,010
+------------------------------------------------------------------------------
+TOTAL           1,661      929.46    128,631,599   20,101,078
+```
+</details>
+
+<details>
+<summary><b>🧾 CSV columns</b></summary>
+
+`datetime_local, timestamp_ms, date, model, kind, input_tokens, output_tokens,
+cache_read_tokens, cache_write_tokens, value_cents, charged_cents,
+requests_costs, is_headless, owning_user` — one row per usage event, sorted by
+time.
+</details>
+
+## 🤔 How it works
+
+A Cursor **API key** (`crsr_…`) can't read usage — that data lives behind your
+web **session**, the same one your browser/app uses on `cursor.com`. This tool
+finds that session locally and asks Cursor's dashboard API for your numbers.
+
+It looks for the session in this order (all **local-only**):
+
+1. `CURSOR_SESSION_TOKEN` environment variable (manual override)
+2. macOS Keychain (written by the `cursor-agent` CLI)
+3. Your OS keyring, if the optional `keyring` package is installed
+4. The Cursor app's local state database (works on every OS)
+
+If it can't find one, sign in to the Cursor app and run it again.
+
+<details>
+<summary><b>🔍 Where exactly the session lives (per OS)</b></summary>
+
+The Cursor IDE stores the session token in a small SQLite file
+(`state.vscdb` → key `cursorAuth/accessToken`), in the same place on every OS:
+
+| OS | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` |
+| Linux | `~/.config/Cursor/User/globalStorage/state.vscdb` |
+| Windows | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` |
+
+Want the full reverse-engineering story (and a recipe to rebuild this tool)? See
+**[docs/HOW_THIS_WAS_BUILT.md](docs/HOW_THIS_WAS_BUILT.md)**.
+</details>
+
+### Manual override
+
+On any OS you can skip auto-detection entirely:
+
+```bash
+# cursor.com → DevTools → Application → Cookies → copy WorkosCursorSessionToken
+export CURSOR_SESSION_TOKEN='user_…::eyJhbGci…'
+cursor-usage
+```
+
+## 🔒 Privacy & security
+
+- The tool only **reads** your existing local session — it never writes,
+  refreshes, or sends it anywhere except `cursor.com`.
+- **No telemetry. No third-party calls.**
+- CSV exports contain your own usage data; they're git-ignored by default so you
+  don't commit them by accident.
+
+## ⚠️ Good to know
+
+- **`$ value` is compute consumed, not money owed.** On plans where usage-based
+  pricing is off, your bill is just the flat subscription — these figures show
+  the value of the compute included in your plan.
+- This uses Cursor's **internal, undocumented** dashboard API. It works great
+  today, but Cursor could change it at any time. If something breaks, please open
+  an issue.
+- If your session has expired, sign back in to Cursor and run the command again.
+
+## 🛠️ Install options
+
+```bash
+pip install cursor-usage                 # from PyPI (once published)
+pip install .                                # from a local clone
+pip install "cursor-usage[keyring]"      # + OS-keyring lookup on Linux/Windows
+```
+
+Requires Python 3.8+.
+
+## 🤝 Contributing
+
+Issues and PRs are welcome. Run the tests with:
+
+```bash
+pip install pytest && pytest -q
+```
+
+## 📄 License
+
+[MIT](LICENSE) — do whatever you like.

cursor_usage-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cursor_usage/__init__.py,sha256=BzumsGS8tLLc5jmkNughJ75hqeGiDNmWyE7wDPUq77E,107
+cursor_usage/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+cursor_usage/api.py,sha256=dm1p7JBEDrB9sxIwL0LzilB4FjXs6_gJbaa6XCDlnZE,3853
+cursor_usage/auth.py,sha256=BvNdntC9Svpj1TbIzsO3u12Hizwk1A8DnoU457ksDSc,6615
+cursor_usage/cli.py,sha256=4rMOsL_BclElj8jKXAJExdWk5I6dt0WaogUaFi19T6o,5018
+cursor_usage/report.py,sha256=Ii6Tf2atfzx6XhYy6H_6DFtdXYUCKhXS7MZafRTE0ME,4725
+cursor_usage-0.1.0.dist-info/licenses/LICENSE,sha256=QPMxh-V7v3qMLQLCYqWtJ_UW7L9wiYK709SGi285LJM,1082
+cursor_usage-0.1.0.dist-info/METADATA,sha256=0eIJZHztrsfSWKaK9YUsWiZbaXFxUFkRi9yrGAsQfbM,8027
+cursor_usage-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cursor_usage-0.1.0.dist-info/entry_points.txt,sha256=CUDRlZjULmG8yccbcKMy6rWurDgYGvwQtHxHhVevYVQ,55
+cursor_usage-0.1.0.dist-info/top_level.txt,sha256=bVAUdvpuBuSZWi-CowqosY8EmoHueGwrC3w79xjxOh4,13
+cursor_usage-0.1.0.dist-info/RECORD,,

cursor_usage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cursor_usage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cursor-usage = cursor_usage.cli:main

cursor_usage-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cursor-usage contributors
+
+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.

cursor_usage-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cursor_usage