📊 cursor-usage

See your Cursor usage, spend, and per-event logs — right from your terminal.

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.

==============================================================================
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
...

==============================================================================
CURSOR CYCLE LIMITS  |  resets 2026-07-04
==============================================================================
Composer / Auto [###########...................]   36.7% used,   63.3% left
Other models    [####..........................]   12.4% used,   87.6% left
Included usage  $146.80 of $400.00 used  ($253.20 left)

✨ Features

• One command, real numbers — per-model tokens and compute value for the current billing month.
• 📊 Cycle limits — the default summary also shows % used / % left before hitting your plan's rate limit, split into Composer / Auto (composer-2.5, composer-2.5-fast, Auto) vs Other models.
• 📅 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

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

Flags combine — e.g. cursor-usage --by-day --csv june.csv --month 2026-06.

==============================================================================
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

🤔 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.

Manual override

On any OS you can skip auto-detection entirely:

# 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

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:

pip install pytest && pytest -q

📄 License

MIT — do whatever you like.