cursor-cli-usage 0.1.0__tar.gz

cursor_cli_usage-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: false
+      - name: Verify version tag
+        run: test "$GITHUB_REF_NAME" = "v$(uv --no-config version --short)"
+      - name: Test
+        run: uv --no-config run --locked python -m unittest discover -s tests
+      - name: Build
+        run: uv --no-config build --no-sources
+      - name: Publish
+        run: uv publish --trusted-publishing always

cursor_cli_usage-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.py[cod]
+.ruff_cache/
+dist/*
+!dist/.gitignore

cursor_cli_usage-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: cursor-cli-usage
+Version: 0.1.0
+Summary: Cursor CLI account quota monitor using local Cursor authentication
+Project-URL: Homepage, https://github.com/wakamex/cursor-cli-usage
+Project-URL: Source, https://github.com/wakamex/cursor-cli-usage
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# cursor-cli-usage
+
+Cursor account usage and quota monitor. It follows the same dependency-free
+interface as the other `/code/*usage` tools.
+
+The tool targets the Cursor CLI harness, but reports account-wide Cursor quota.
+It does not estimate usage from local CLI sessions.
+
+## Example output
+
+```text
+Cursor usage
+Status: live
+Plan: 6.1% used
+Resets: 1787506237000
+```
+
+Statusline:
+
+```text
+cursor:q:6.1%used reset:12d20h
+```
+
+## Install
+
+```bash
+uv tool install cursor-cli-usage
+```
+
+For local development:
+
+```bash
+uv tool install .
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `cursor-cli-usage` | Show current account usage |
+| `cursor-cli-usage status` | Same as above |
+| `cursor-cli-usage json` | Print normalized JSON |
+| `cursor-cli-usage statusline` | Print compact cached output |
+| `cursor-cli-usage refresh` | Refresh the cache and print status |
+| `cursor-cli-usage daemon [-i SECS]` | Keep the cache fresh |
+| `cursor-cli-usage install` | Print installation instructions |
+
+## Authentication and data
+
+For every live request, the tool first asks the installed Cursor CLI for its
+current authentication state with `agent status --format json`. If the CLI is
+unavailable, it falls back to `cursorAuth/accessToken` in Cursor IDE's local
+`state.vscdb`. It sends only the current access token to Cursor's dashboard
+usage service. It never refreshes, rotates, or modifies Cursor-owned
+credentials.
+
+The normalized JSON includes:
+
+- `provider`, `source`, `retrieved_at`, and `status`
+- billing-cycle start and end
+- plan and spend-limit usage
+- models assigned to Cursor's automatic usage bucket
+
+`status` is `live`, `cached`, `stale`, or `unavailable`. Errors and caches do
+not include the access token or Cursor account identity.
+
+The tool writes only its own non-secret cache at
+`~/.cursor/usage-limits.json`. JSON results report whether they are `live`,
+`cached`, `stale`, or `unavailable`.
+
+Environment overrides:
+
+- `CURSOR_USAGE_AGENT`: alternate Cursor CLI executable
+- `CURSOR_USAGE_STATE_DB`: alternate Cursor `state.vscdb` path
+- `CURSOR_USAGE_FILE`: alternate cache path
+
+The usage endpoint is undocumented and may change when Cursor changes its
+dashboard implementation.
+
+## Options
+
+```text
+usage: cursor-cli-usage [-h] [-i INTERVAL] [--max-age MAX_AGE] [--refresh]
+                        {status,json,daemon,statusline,refresh,install}
+```
+
+- `--max-age SECS`: maximum cache age used by `statusline`
+- `--refresh`: bypass the cache for `statusline`
+- `-i SECS`: daemon refresh interval
+
+## Development
+
+```bash
+uv --no-config lock --check
+uv --no-config run --locked python -m unittest discover -s tests
+uv --no-config build --no-sources
+```

cursor_cli_usage-0.1.0/README.md

@@ -0,0 +1,97 @@
+# cursor-cli-usage
+
+Cursor account usage and quota monitor. It follows the same dependency-free
+interface as the other `/code/*usage` tools.
+
+The tool targets the Cursor CLI harness, but reports account-wide Cursor quota.
+It does not estimate usage from local CLI sessions.
+
+## Example output
+
+```text
+Cursor usage
+Status: live
+Plan: 6.1% used
+Resets: 1787506237000
+```
+
+Statusline:
+
+```text
+cursor:q:6.1%used reset:12d20h
+```
+
+## Install
+
+```bash
+uv tool install cursor-cli-usage
+```
+
+For local development:
+
+```bash
+uv tool install .
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `cursor-cli-usage` | Show current account usage |
+| `cursor-cli-usage status` | Same as above |
+| `cursor-cli-usage json` | Print normalized JSON |
+| `cursor-cli-usage statusline` | Print compact cached output |
+| `cursor-cli-usage refresh` | Refresh the cache and print status |
+| `cursor-cli-usage daemon [-i SECS]` | Keep the cache fresh |
+| `cursor-cli-usage install` | Print installation instructions |
+
+## Authentication and data
+
+For every live request, the tool first asks the installed Cursor CLI for its
+current authentication state with `agent status --format json`. If the CLI is
+unavailable, it falls back to `cursorAuth/accessToken` in Cursor IDE's local
+`state.vscdb`. It sends only the current access token to Cursor's dashboard
+usage service. It never refreshes, rotates, or modifies Cursor-owned
+credentials.
+
+The normalized JSON includes:
+
+- `provider`, `source`, `retrieved_at`, and `status`
+- billing-cycle start and end
+- plan and spend-limit usage
+- models assigned to Cursor's automatic usage bucket
+
+`status` is `live`, `cached`, `stale`, or `unavailable`. Errors and caches do
+not include the access token or Cursor account identity.
+
+The tool writes only its own non-secret cache at
+`~/.cursor/usage-limits.json`. JSON results report whether they are `live`,
+`cached`, `stale`, or `unavailable`.
+
+Environment overrides:
+
+- `CURSOR_USAGE_AGENT`: alternate Cursor CLI executable
+- `CURSOR_USAGE_STATE_DB`: alternate Cursor `state.vscdb` path
+- `CURSOR_USAGE_FILE`: alternate cache path
+
+The usage endpoint is undocumented and may change when Cursor changes its
+dashboard implementation.
+
+## Options
+
+```text
+usage: cursor-cli-usage [-h] [-i INTERVAL] [--max-age MAX_AGE] [--refresh]
+                        {status,json,daemon,statusline,refresh,install}
+```
+
+- `--max-age SECS`: maximum cache age used by `statusline`
+- `--refresh`: bypass the cache for `statusline`
+- `-i SECS`: daemon refresh interval
+
+## Development
+
+```bash
+uv --no-config lock --check
+uv --no-config run --locked python -m unittest discover -s tests
+uv --no-config build --no-sources
+```

cursor_cli_usage-0.1.0/dist/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

cursor_cli_usage-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "cursor-cli-usage"
+version = "0.1.0"
+description = "Cursor CLI account quota monitor using local Cursor authentication"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cursor_cli_usage"]
+
+[project.urls]
+Homepage = "https://github.com/wakamex/cursor-cli-usage"
+Source = "https://github.com/wakamex/cursor-cli-usage"
+
+[project.scripts]
+cursor-cli-usage = "cursor_cli_usage:main"

cursor_cli_usage-0.1.0/src/cursor_cli_usage/__init__.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""Cursor account usage monitor using Cursor-owned local authentication."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import signal
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from datetime import UTC, datetime
+from pathlib import Path
+
+DEFAULT_USAGE_FILE = Path.home() / ".cursor" / "usage-limits.json"
+USAGE_URL = "https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage"
+CACHE_MAX_AGE = 300
+DAEMON_INTERVAL = 300
+
+
+def _iso_now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _parse_iso(value: object) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed.replace(tzinfo=UTC) if parsed.tzinfo is None else parsed
+
+
+def _format_reset(value: object) -> str:
+    if not isinstance(value, str | int | float):
+        return ""
+    try:
+        reset = datetime.fromtimestamp(float(value) / 1000, UTC)
+    except (TypeError, ValueError, OSError):
+        parsed = _parse_iso(value)
+        if parsed is None:
+            return ""
+        reset = parsed
+    minutes = max(0, int((reset - datetime.now(UTC)).total_seconds()) // 60)
+    if minutes >= 1440:
+        return f"{minutes // 1440}d{(minutes % 1440) // 60}h"
+    if minutes >= 60:
+        return f"{minutes // 60}h{minutes % 60}m"
+    return f"{minutes}m"
+
+
+def get_state_db() -> Path:
+    override = os.environ.get("CURSOR_USAGE_STATE_DB")
+    if override:
+        return Path(override).expanduser()
+    if platform.system() == "Darwin":
+        return (
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Cursor"
+            / "User"
+            / "globalStorage"
+            / "state.vscdb"
+        )
+    if platform.system() == "Windows":
+        app_data = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+        return app_data / "Cursor" / "User" / "globalStorage" / "state.vscdb"
+    return Path.home() / ".config" / "Cursor" / "User" / "globalStorage" / "state.vscdb"
+
+
+def get_usage_file() -> Path:
+    override = os.environ.get("CURSOR_USAGE_FILE")
+    return Path(override).expanduser() if override else DEFAULT_USAGE_FILE
+
+
+def _find_cursor_cli() -> str | None:
+    override = os.environ.get("CURSOR_USAGE_AGENT")
+    if override:
+        return str(Path(override).expanduser())
+    for name in ("agent", "cursor-agent"):
+        if executable := shutil.which(name):
+            return executable
+    return None
+
+
+def _get_cli_access_token() -> str | None:
+    executable = _find_cursor_cli()
+    if not executable:
+        return None
+    try:
+        result = subprocess.run(
+            [executable, "status", "--format", "json"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode:
+        return None
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+    auth = payload.get("auth") if isinstance(payload, dict) else None
+    token = auth.get("accessToken") if isinstance(auth, dict) else None
+    return token if isinstance(token, str) and token else None
+
+
+def _get_ide_access_token() -> str | None:
+    path = get_state_db()
+    if not path.is_file():
+        return None
+    try:
+        connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        try:
+            row = connection.execute(
+                "SELECT value FROM ItemTable WHERE key = ? LIMIT 1",
+                ("cursorAuth/accessToken",),
+            ).fetchone()
+        finally:
+            connection.close()
+    except sqlite3.Error as exc:
+        raise RuntimeError(f"Could not read Cursor authentication from {path}") from exc
+    return row[0] if row and isinstance(row[0], str) and row[0] else None
+
+
+def get_access_token() -> str:
+    """Read the current access token without refreshing or modifying Cursor state."""
+    if token := _get_cli_access_token():
+        return token
+    if token := _get_ide_access_token():
+        return token
+    raise RuntimeError(
+        "Cursor CLI is not logged in and no Cursor IDE session was found"
+    )
+
+
+def _number(value: object) -> int | float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int | float):
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = float(value)
+        except ValueError:
+            return None
+        return int(parsed) if parsed.is_integer() else parsed
+    return None
+
+
+def _usage_bucket(value: object) -> dict | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        key: parsed
+        for key, source in (
+            ("limit", "limit"),
+            ("used", "used"),
+            ("remaining", "remaining"),
+            ("percent_used", "totalPercentUsed"),
+        )
+        if (parsed := _number(value.get(source))) is not None
+    }
+
+
+def fetch_usage() -> dict:
+    token = get_access_token()
+    request = urllib.request.Request(
+        USAGE_URL,
+        data=b"{}",
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Connect-Protocol-Version": "1",
+            "User-Agent": "cursor-cli-usage/0.1",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            payload = json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            raise RuntimeError(
+                "Cursor access token is no longer accepted; sign in with Cursor again"
+            ) from exc
+        raise RuntimeError(f"Cursor usage API returned HTTP {exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise RuntimeError("Cursor usage API is unavailable") from exc
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("Cursor usage API returned invalid JSON") from exc
+    if not isinstance(payload, dict):
+        raise RuntimeError("Cursor usage API returned an unexpected response")
+    return payload
+
+
+def _normalize(payload: dict) -> dict:
+    models = payload.get("autoBucketModels")
+    return {
+        "billing_cycle": {
+            "start": payload.get("billingCycleStart"),
+            "end": payload.get("billingCycleEnd"),
+        },
+        "plan_usage": _usage_bucket(payload.get("planUsage")),
+        "spend_limit_usage": _usage_bucket(payload.get("spendLimitUsage")),
+        "auto_models": models if isinstance(models, list) else [],
+    }
+
+
+def build_usage_json() -> dict:
+    updated_at = _iso_now()
+    try:
+        usage = _normalize(fetch_usage())
+    except Exception as exc:
+        return {
+            "provider": "cursor",
+            "status": "unavailable",
+            "source": "cursor_dashboard_api",
+            "retrieved_at": updated_at,
+            "error": str(exc),
+        }
+    return {
+        "provider": "cursor",
+        "status": "live",
+        "source": "cursor_dashboard_api",
+        "retrieved_at": updated_at,
+        **usage,
+    }
+
+
+def write_usage_file(data: dict) -> None:
+    path = get_usage_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(fd, "w") as handle:
+            json.dump(data, handle, indent=2)
+            handle.write("\n")
+        os.replace(temporary, path)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def _read_cache() -> dict | None:
+    try:
+        data = json.loads(get_usage_file().read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def get_cached_usage(max_age: int = CACHE_MAX_AGE, force_refresh: bool = False) -> dict:
+    cached = _read_cache()
+    if not force_refresh and cached:
+        retrieved = _parse_iso(cached.get("retrieved_at"))
+        if retrieved and (datetime.now(UTC) - retrieved).total_seconds() < max_age:
+            return {**cached, "status": "cached"}
+    fresh = build_usage_json()
+    if fresh["status"] == "live":
+        write_usage_file(fresh)
+        return fresh
+    if cached:
+        return {**cached, "status": "stale", "refresh_error": fresh.get("error")}
+    return fresh
+
+
+def _summary_usage(data: dict) -> dict | None:
+    for key in ("plan_usage", "spend_limit_usage"):
+        bucket = data.get(key)
+        if isinstance(bucket, dict) and bucket.get("percent_used") is not None:
+            return bucket
+    return None
+
+
+def _statusline_text(data: dict) -> str:
+    bucket = _summary_usage(data)
+    if not bucket:
+        return "cursor:q:unavailable"
+    used = float(bucket["percent_used"])
+    reset = _format_reset((data.get("billing_cycle") or {}).get("end"))
+    parts = [f"cursor:q:{used:.1f}%used"]
+    if reset:
+        parts.append(f"reset:{reset}")
+    if data.get("status") in {"cached", "stale"}:
+        parts.append(str(data["status"]))
+    return " ".join(parts)
+
+
+def _print_status(data: dict) -> None:
+    print("Cursor usage")
+    print(f"Status: {data['status']}")
+    bucket = data.get("plan_usage")
+    if isinstance(bucket, dict):
+        if bucket.get("percent_used") is not None:
+            print(f"Plan: {float(bucket['percent_used']):g}% used")
+        if bucket.get("used") is not None and bucket.get("limit") is not None:
+            print(f"Usage: {bucket['used']} of {bucket['limit']}")
+    spend = data.get("spend_limit_usage")
+    if isinstance(spend, dict) and spend.get("percent_used") is not None:
+        print(f"Spend limit: {float(spend['percent_used']):g}% used")
+    cycle = data.get("billing_cycle") or {}
+    if cycle.get("end"):
+        print(f"Resets: {cycle['end']}")
+    if data.get("error"):
+        print(f"Error: {data['error']}")
+    if data.get("refresh_error"):
+        print(f"Refresh error: {data['refresh_error']}")
+
+
+def cmd_status(_args: argparse.Namespace) -> None:
+    _print_status(build_usage_json())
+
+
+def cmd_json(_args: argparse.Namespace) -> None:
+    print(json.dumps(build_usage_json(), indent=2))
+
+
+def cmd_statusline(args: argparse.Namespace) -> None:
+    print(_statusline_text(get_cached_usage(args.max_age, args.refresh)))
+
+
+def cmd_refresh(_args: argparse.Namespace) -> None:
+    data = build_usage_json()
+    if data["status"] == "live":
+        write_usage_file(data)
+    _print_status(data)
+
+
+def cmd_daemon(args: argparse.Namespace) -> None:
+    signal.signal(signal.SIGINT, lambda *_: sys.exit(0))
+    if hasattr(signal, "SIGTERM"):
+        signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    print(f"cursor-cli-usage daemon started (refreshing every {args.interval}s)")
+    print(f"Writing to {get_usage_file()}")
+    while True:
+        data = build_usage_json()
+        if data["status"] == "live":
+            write_usage_file(data)
+        print(f"[{datetime.now().strftime('%H:%M:%S')}] {_statusline_text(data)}")
+        time.sleep(args.interval)
+
+
+def cmd_install(_args: argparse.Namespace) -> None:
+    print(
+        "Install with:\n  uv tool install cursor-cli-usage\n\nThen run:\n  cursor-cli-usage"
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Cursor account usage monitor")
+    parser.add_argument(
+        "command",
+        nargs="?",
+        default="status",
+        choices=["status", "json", "daemon", "statusline", "refresh", "install"],
+    )
+    parser.add_argument("-i", "--interval", type=int, default=DAEMON_INTERVAL)
+    parser.add_argument("--max-age", type=int, default=CACHE_MAX_AGE)
+    parser.add_argument("--refresh", action="store_true")
+    return parser
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+    commands = {
+        "status": cmd_status,
+        "json": cmd_json,
+        "daemon": cmd_daemon,
+        "statusline": cmd_statusline,
+        "refresh": cmd_refresh,
+        "install": cmd_install,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

cursor_cli_usage-0.1.0/src/cursor_cli_usage/__main__.py

@@ -0,0 +1,3 @@
+from cursor_cli_usage import main
+
+main()

cursor_cli_usage-0.1.0/tests/test_cursor_cli_usage.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import tempfile
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+import cursor_cli_usage as cursor_usage
+
+
+class FakeResponse:
+    def __init__(self, payload: dict):
+        self.payload = payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        return False
+
+    def read(self):
+        return json.dumps(self.payload).encode()
+
+
+class CursorUsageTests(unittest.TestCase):
+    def test_access_token_is_read_from_database_without_writes(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            database = Path(temporary) / "state.vscdb"
+            connection = sqlite3.connect(database)
+            try:
+                connection.execute("CREATE TABLE ItemTable (key TEXT, value TEXT)")
+                connection.execute(
+                    "INSERT INTO ItemTable VALUES (?, ?)",
+                    ("cursorAuth/accessToken", "local-token"),
+                )
+                connection.commit()
+            finally:
+                connection.close()
+            before = database.read_bytes()
+            with mock.patch.dict(
+                cursor_usage.os.environ, {"CURSOR_USAGE_STATE_DB": str(database)}
+            ):
+                with mock.patch.object(
+                    cursor_usage, "_get_cli_access_token", return_value=None
+                ):
+                    self.assertEqual(cursor_usage.get_access_token(), "local-token")
+            self.assertEqual(database.read_bytes(), before)
+
+    def test_cli_status_is_preferred_and_only_access_token_is_returned(self):
+        completed = mock.Mock(
+            returncode=0,
+            stdout=json.dumps(
+                {
+                    "authenticated": True,
+                    "auth": {
+                        "accessToken": "cli-access",
+                        "refreshToken": "must-not-be-returned",
+                    },
+                }
+            ),
+        )
+        with (
+            mock.patch.object(cursor_usage, "_find_cursor_cli", return_value="agent"),
+            mock.patch.object(
+                cursor_usage.subprocess, "run", return_value=completed
+            ) as run,
+            mock.patch.object(cursor_usage, "_get_ide_access_token") as ide,
+        ):
+            self.assertEqual(cursor_usage.get_access_token(), "cli-access")
+        run.assert_called_once_with(
+            ["agent", "status", "--format", "json"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        ide.assert_not_called()
+
+    def test_fetch_uses_bearer_token_and_connect_protocol(self):
+        payload = {"planUsage": {"limit": 2000, "used": 500, "totalPercentUsed": 25}}
+
+        def fake_urlopen(request, timeout):
+            self.assertEqual(request.get_header("Authorization"), "Bearer token")
+            self.assertEqual(request.get_header("Connect-protocol-version"), "1")
+            self.assertEqual(timeout, 15)
+            return FakeResponse(payload)
+
+        with (
+            mock.patch.object(cursor_usage, "get_access_token", return_value="token"),
+            mock.patch.object(
+                cursor_usage.urllib.request, "urlopen", side_effect=fake_urlopen
+            ),
+        ):
+            self.assertEqual(cursor_usage.fetch_usage(), payload)
+
+    def test_build_normalizes_current_period_usage(self):
+        payload = {
+            "billingCycleStart": "1000",
+            "billingCycleEnd": "2000",
+            "planUsage": {"limit": 2000, "remaining": 1500, "totalPercentUsed": 25},
+            "spendLimitUsage": {"limit": "1000", "used": "100"},
+            "autoBucketModels": ["auto"],
+        }
+        with mock.patch.object(cursor_usage, "fetch_usage", return_value=payload):
+            data = cursor_usage.build_usage_json()
+        self.assertEqual(data["status"], "live")
+        self.assertEqual(data["plan_usage"]["percent_used"], 25)
+        self.assertEqual(data["spend_limit_usage"]["used"], 100)
+        self.assertEqual(data["auto_models"], ["auto"])
+
+    def test_unauthorized_never_attempts_refresh(self):
+        error = urllib.error.HTTPError(cursor_usage.USAGE_URL, 401, "", {}, None)
+        with (
+            mock.patch.object(cursor_usage, "get_access_token", return_value="expired"),
+            mock.patch.object(
+                cursor_usage.urllib.request, "urlopen", side_effect=error
+            ),
+        ):
+            data = cursor_usage.build_usage_json()
+        self.assertEqual(data["status"], "unavailable")
+        self.assertIn("sign in", data["error"])
+
+    def test_stale_cache_is_returned_when_refresh_fails(self):
+        cached = {
+            "provider": "cursor",
+            "status": "live",
+            "source": "cursor_dashboard_api",
+            "retrieved_at": "2020-01-01T00:00:00+00:00",
+            "plan_usage": {"percent_used": 50},
+        }
+        with tempfile.TemporaryDirectory() as temporary:
+            cache = Path(temporary) / "usage.json"
+            cache.write_text(json.dumps(cached))
+            with (
+                mock.patch.object(cursor_usage, "DEFAULT_USAGE_FILE", cache),
+                mock.patch.object(
+                    cursor_usage,
+                    "build_usage_json",
+                    return_value={"status": "unavailable", "error": "offline"},
+                ),
+            ):
+                result = cursor_usage.get_cached_usage()
+        self.assertEqual(result["status"], "stale")
+        self.assertEqual(result["refresh_error"], "offline")
+
+
+if __name__ == "__main__":
+    unittest.main()

cursor_cli_usage-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[[package]]
+name = "cursor-cli-usage"
+version = "0.1.0"
+source = { editable = "." }