cursor-usage 0.1.1 → 0.1.3

package/README.md

@@ -4,12 +4,12 @@ A CLI tool for analyzing Cursor API usage and membership information, inspired b
 
 ## Features
 
-- ✨ Extract Cursor credentials from local database
-- 🔗 Fetch usage data from Cursor API
-- 💳 Display membership and plan usage information
-- 📊 Show usage breakdown (included vs bonus)
-- 🎯 Track percentage of included usage consumed
-- 🎨 Colorful terminal output
+- Extract Cursor credentials from local database
+- Fetch usage data from Cursor API
+- Display membership and plan usage information
+- Show usage breakdown (included vs bonus)
+- Track percentage of included usage consumed
+- Colorful terminal output
 
 ## Installation
 
@@ -17,6 +17,26 @@ A CLI tool for analyzing Cursor API usage and membership information, inspired b
 npm install
 ```
 
+## Quick Test
+
+You can test the package without installing it locally using npx or bunx:
+
+```bash
+# Test with npx (Node.js)
+npx cursor-usage@latest
+
+# Test with bunx (Bun runtime)
+bunx cursor-usage@latest
+
+# Test specific commands
+npx cursor-usage@latest daily
+npx cursor-usage@latest monthly
+
+# Test with flags
+npx cursor-usage@latest daily --breakdown
+npx cursor-usage@latest weekly --json
+```
+
 ## Usage
 
 ### Commands
@@ -44,8 +64,28 @@ npm run dev -- today
 
 # Show help
 npm run dev -- help
+
+# Show usage with date range
+npm run dev -- daily --since 2026-01-01 --until 2026-01-15
+
+# Show usage with model breakdown
+npm run dev -- daily --breakdown
+
+# Show compact table format
+npm run dev -- monthly --compact
+
+# Output as JSON (detailed reports only)
+npm run dev -- daily --json
 ```
 
+### Flags
+
+- `--since DATE` - Start date (YYYY-MM-DD)
+- `--until DATE` - End date (YYYY-MM-DD)
+- `--breakdown` - Show per-model breakdown
+- `--json` - Output as JSON (machine-readable format)
+- `--compact` - Compact table format
+
 ### Development
 
 ```bash
@@ -59,11 +99,11 @@ npm run build           # Compile TypeScript
 ### Summary View
 
 ```
-📊 ACCOUNT INFORMATION:
+ACCOUNT INFORMATION:
   Membership: pro
   Billing Cycle: <your-billing-cycle>
 
-📊 PLAN USAGE:
+PLAN USAGE:
   Used: 150 / 2000 (7.50%)
   Remaining: 1850
 ```
@@ -136,21 +176,91 @@ USAGE EVENTS FOR Today
 Total Events: 3
 Total Tokens: 3,150
 Total Cost: $0.14
-========================================================================================================================
+==================================================================================================================
+```
+
+### Model Breakdown View (`--breakdown`)
+
+When using `--breakdown`, reports include a detailed per-model breakdown:
+
+```
+==================================================================================================================
+PER-MODEL BREAKDOWN
+==================================================================================================================
+
++---------------+--------+--------------+-------+-------+-------+---------+------------+------------+
+| Model         | Events | Total Tokens | Input | Output| Cost  | Token % | Cost %     |
++---------------+--------+--------------+-------+-------+-------+---------+------------+
+| claude-opus   | 15     | 2,500,000    | 20000 | 15000 | $2.00 | 50.00%  | 40.00%    |
+| claude-sonnet | 10     | 2,000,000    | 15000 | 12000 | $1.60 | 40.00%  | 32.00%    |
+| claude-haiku  | 5      | 500,000      | 5000  | 3000  | $0.40 | 10.00%  | 8.00%     |
++---------------+--------+--------------+-------+-------+-------+---------+------------+
+```
+
+### JSON Output (`--json`)
+
+JSON output provides clean, structured data for programmatic use (no table formatting):
+
+```json
+{
+  "command": "daily",
+  "generatedAt": "2026-01-11T10:30:00.000Z",
+  "period": "last 7 days",
+  "summary": {
+    "totalEvents": 45,
+    "totalTokens": 539301,
+    "totalCost": 0.82
+  },
+  "data": [
+    {
+      "date": "2026-01-11",
+      "eventCount": 3,
+      "totalTokens": 539301,
+      "inputTokens": 381,
+      "outputTokens": 7081,
+      "totalCost": 0.82,
+      "models": {
+        "claude-4.5-opus-high-thinking": 3
+      }
+    }
+  ],
+  "breakdown": [
+    {
+      "model": "claude-opus",
+      "count": 15,
+      "totalTokens": 250000,
+      "inputTokens": 20000,
+      "outputTokens": 15000,
+      "totalCost": 2.0,
+      "tokenPercent": 50.0,
+      "costPercent": 40.0
+    }
+  ]
+}
 ```
 
-## How It Works
+### Compact Table Format (`--compact`)
 
-1. **Extracts credentials** from `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`
-   - User ID from `workbench.experiments.statsigBootstrap`
-   - Access Token from `cursorAuth/accessToken`
-   - Email and membership (optional)
+The `--compact` flag provides a more condensed table layout:
 
-2. **Authenticates** with Cursor API using `WorkosCursorSessionToken` cookie
+```
+==================================================================================================================
+DAILY USAGE REPORT (Last 7 days)
+==================================================================================================================
 
-3. **Fetches usage data** from `https://cursor.com/api/usage-summary`
+Date        Events  Tokens      Cost   Models
+2026-01-11  3       539,301     $0.82  claude-4.5-opus-high-thinking(3)
+2026-01-10  5       1,200,450   $1.45  claude-sonnet(4), claude-opus(1)
+2026-01-09  2       89,320      $0.12  claude-haiku(2)
 
-4. **Parses and displays** membership, plan usage, and billing information
+==================================================================================================================
+SUMMARY
+==================================================================================================================
+Total Events: 10
+Total Tokens: 1,829,071
+Total Cost: $2.39
+==================================================================================================================
+```
 
 ## Environment Variables
 
@@ -168,15 +278,6 @@ src/
 └── _consts.ts        # Constants & configuration
 ```
 
-## API Response Structure
-
-The tool fetches data from Cursor's `/api/usage-summary` endpoint which returns:
-- Billing cycle information
-- Membership type (pro, hobby, etc.)
-- Plan usage (used/limit/remaining)
-- On-demand usage status
-- Display messages about usage percentage
-
 ## Features Implemented
 
 - ✅ Daily usage reports with table formatting
@@ -187,17 +288,6 @@ The tool fetches data from Cursor's `/api/usage-summary` endpoint which returns:
 - ✅ Flexible date range querying
 - ✅ Colorized CLI output
 
-## Future Enhancements
-
-- [ ] JSON output format (`--json`)
-- [ ] Date range queries (`--from 2026-01-01 --to 2026-01-31`)
-- [ ] Weekly/monthly aggregations
-- [ ] Historical data caching
-- [ ] Cost projections
-- [ ] Team usage analysis
-- [ ] Export to CSV/JSON
-- [ ] Web dashboard
-- [ ] Webhook notifications
 
 ## License
 

package/dist/cli.js

@@ -81,17 +81,22 @@ function displayResults(data) {
     const plan = data.individualUsage?.plan;
     if (plan) {
         logger.log('\n📊 PLAN USAGE:');
-        logger.log(`  Used: ${plan.used} / ${plan.limit} (${(plan.totalPercentUsed * 100).toFixed(2)}%)`);
-        logger.log(`  Remaining: ${plan.remaining}`);
+        logger.log(`  Used: ${plan.used} / ${plan.limit} (${plan.limit > 0 ? ((plan.used / plan.limit) * 100).toFixed(2) : '0.00'}%)`);
+        logger.log(`  Remaining: ${plan.limit - plan.used}`);
         logger.log(`  Breakdown:`);
         logger.log(`    - Included: ${plan.breakdown?.included || 0}`);
         logger.log(`    - Bonus: ${plan.breakdown?.bonus || 0}`);
+        logger.log(`    - Total: ${plan.breakdown?.total || 0}`);
     }
     // On-demand usage
     const onDemand = data.individualUsage?.onDemand;
     if (onDemand && onDemand.enabled) {
         logger.log('\n💰 ON-DEMAND USAGE:');
         logger.log(`  Used: ${onDemand.used}`);
+        if (onDemand.limit !== null) {
+            logger.log(`  Limit: ${onDemand.limit}`);
+            logger.log(`  Remaining: ${onDemand.remaining !== null ? onDemand.remaining : (onDemand.limit - onDemand.used)}`);
+        }
         logger.log(`  Status: Enabled`);
     }
     // Display messages

package/dist/commands.js

@@ -71,50 +71,53 @@ export async function showDailyReport(credentials, days = 7, options = {}, outpu
         logger.warn('No usage events found for this period');
         return;
     }
-    logger.log('');
     // Group and calculate stats
     const grouped = groupByDay(events);
     const stats = calculateDailyStats(grouped);
-    // Display table
-    logger.log('\n' + '='.repeat(100));
-    logger.log(`DAILY USAGE REPORT (Last ${days} days)`);
-    logger.log('='.repeat(100) + '\n');
-    const tableData = stats.map((day) => {
-        const modelList = Array.from(day.models.entries())
-            .map(([model, count]) => `${model}(${count})`)
-            .join(', ');
-        return [
-            day.date,
-            day.eventCount.toString(),
-            day.totalTokens.toLocaleString(),
-            day.inputTokens.toLocaleString(),
-            day.outputTokens.toLocaleString(),
-            `$${day.totalCost.toFixed(2)}`,
-            modelList || 'N/A',
-        ];
-    });
-    const table = createTable(['Date', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
-    logger.log(table);
-    // Summary
-    const totalEvents = stats.reduce((sum, day) => sum + day.eventCount, 0);
-    const totalTokens = stats.reduce((sum, day) => sum + day.totalTokens, 0);
-    const totalCost = stats.reduce((sum, day) => sum + day.totalCost, 0);
-    logger.log('\n' + '='.repeat(100));
-    logger.log('SUMMARY');
-    logger.log('='.repeat(100));
-    logger.log(`Total Events: ${totalEvents}`);
-    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
-    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
-    logger.log('='.repeat(100) + '\n');
-    // Show breakdown if requested
-    if (options.breakdown) {
-        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
-    }
-    // Output JSON if requested
     if (outputJson) {
+        // Output JSON only - no table display
         const jsonOutput = statsToJSON('daily', stats, events, { breakdown: options.breakdown, period: `last ${days} days` });
         console.log(jsonOutput);
     }
+    else {
+        // Display table and summary
+        logger.log('');
+        // Display table
+        logger.log('\n' + '='.repeat(100));
+        logger.log(`DAILY USAGE REPORT (Last ${days} days)`);
+        logger.log('='.repeat(100) + '\n');
+        const tableData = stats.map((day) => {
+            const modelList = Array.from(day.models.entries())
+                .map(([model, count]) => `${model}(${count})`)
+                .join(', ');
+            return [
+                day.date,
+                day.eventCount.toString(),
+                day.totalTokens.toLocaleString(),
+                day.inputTokens.toLocaleString(),
+                day.outputTokens.toLocaleString(),
+                `$${day.totalCost.toFixed(2)}`,
+                modelList || 'N/A',
+            ];
+        });
+        const table = createTable(['Date', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+        logger.log(table);
+        // Summary
+        const totalEvents = stats.reduce((sum, day) => sum + day.eventCount, 0);
+        const totalTokens = stats.reduce((sum, day) => sum + day.totalTokens, 0);
+        const totalCost = stats.reduce((sum, day) => sum + day.totalCost, 0);
+        logger.log('\n' + '='.repeat(100));
+        logger.log('SUMMARY');
+        logger.log('='.repeat(100));
+        logger.log(`Total Events: ${totalEvents}`);
+        logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+        logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+        logger.log('='.repeat(100) + '\n');
+        // Show breakdown if requested
+        if (options.breakdown) {
+            displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+        }
+    }
 }
 /**
  * Show monthly usage report
@@ -136,38 +139,41 @@ export async function showMonthlyReport(credentials, months = 3, options = {}, o
         logger.warn('No usage events found for this period');
         return;
     }
-    logger.log('');
     // Group and calculate stats
     const grouped = groupByMonth(events);
     const stats = calculateMonthlyStats(grouped);
-    // Display table
-    logger.log('\n' + '='.repeat(100));
-    logger.log(`MONTHLY USAGE REPORT (Last ${months} months)`);
-    logger.log('='.repeat(100) + '\n');
-    const tableData = formatMonthlyStatsTable(stats);
-    const table = createTable(['Month', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
-    logger.log(table);
-    // Summary
-    const totalEvents = stats.reduce((sum, month) => sum + month.eventCount, 0);
-    const totalTokens = stats.reduce((sum, month) => sum + month.totalTokens, 0);
-    const totalCost = stats.reduce((sum, month) => sum + month.totalCost, 0);
-    logger.log('\n' + '='.repeat(100));
-    logger.log('SUMMARY');
-    logger.log('='.repeat(100));
-    logger.log(`Total Events: ${totalEvents}`);
-    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
-    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
-    logger.log(`Average per month: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
-    logger.log('='.repeat(100) + '\n');
-    // Show breakdown if requested
-    if (options.breakdown) {
-        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
-    }
-    // Output JSON if requested
     if (outputJson) {
+        // Output JSON only - no table display
         const jsonOutput = statsToJSON('monthly', stats, events, { breakdown: options.breakdown, period: `last ${months} months` });
         console.log(jsonOutput);
     }
+    else {
+        // Display table and summary
+        logger.log('');
+        // Display table
+        logger.log('\n' + '='.repeat(100));
+        logger.log(`MONTHLY USAGE REPORT (Last ${months} months)`);
+        logger.log('='.repeat(100) + '\n');
+        const tableData = formatMonthlyStatsTable(stats);
+        const table = createTable(['Month', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+        logger.log(table);
+        // Summary
+        const totalEvents = stats.reduce((sum, month) => sum + month.eventCount, 0);
+        const totalTokens = stats.reduce((sum, month) => sum + month.totalTokens, 0);
+        const totalCost = stats.reduce((sum, month) => sum + month.totalCost, 0);
+        logger.log('\n' + '='.repeat(100));
+        logger.log('SUMMARY');
+        logger.log('='.repeat(100));
+        logger.log(`Total Events: ${totalEvents}`);
+        logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+        logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+        logger.log(`Average per month: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
+        logger.log('='.repeat(100) + '\n');
+        // Show breakdown if requested
+        if (options.breakdown) {
+            displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+        }
+    }
 }
 /**
  * Show weekly usage report
@@ -188,38 +194,41 @@ export async function showWeeklyReport(credentials, weeks = 4, options = {}, out
         logger.warn('No usage events found for this period');
         return;
     }
-    logger.log('');
     // Group and calculate stats
     const grouped = groupByWeek(events);
     const stats = calculateWeeklyStats(grouped);
-    // Display table
-    logger.log('\n' + '='.repeat(120));
-    logger.log(`WEEKLY USAGE REPORT (Last ${weeks} weeks)`);
-    logger.log('='.repeat(120) + '\n');
-    const tableData = formatWeeklyStatsTable(stats);
-    const table = createTable(['Week', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
-    logger.log(table);
-    // Summary
-    const totalEvents = stats.reduce((sum, week) => sum + week.eventCount, 0);
-    const totalTokens = stats.reduce((sum, week) => sum + week.totalTokens, 0);
-    const totalCost = stats.reduce((sum, week) => sum + week.totalCost, 0);
-    logger.log('\n' + '='.repeat(120));
-    logger.log('SUMMARY');
-    logger.log('='.repeat(120));
-    logger.log(`Total Events: ${totalEvents}`);
-    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
-    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
-    logger.log(`Average per week: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
-    logger.log('='.repeat(120) + '\n');
-    // Show breakdown if requested
-    if (options.breakdown) {
-        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
-    }
-    // Output JSON if requested
     if (outputJson) {
+        // Output JSON only - no table display
         const jsonOutput = statsToJSON('weekly', stats, events, { breakdown: options.breakdown, period: `last ${weeks} weeks` });
         console.log(jsonOutput);
     }
+    else {
+        // Display table and summary
+        logger.log('');
+        // Display table
+        logger.log('\n' + '='.repeat(120));
+        logger.log(`WEEKLY USAGE REPORT (Last ${weeks} weeks)`);
+        logger.log('='.repeat(120) + '\n');
+        const tableData = formatWeeklyStatsTable(stats);
+        const table = createTable(['Week', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+        logger.log(table);
+        // Summary
+        const totalEvents = stats.reduce((sum, week) => sum + week.eventCount, 0);
+        const totalTokens = stats.reduce((sum, week) => sum + week.totalTokens, 0);
+        const totalCost = stats.reduce((sum, week) => sum + week.totalCost, 0);
+        logger.log('\n' + '='.repeat(120));
+        logger.log('SUMMARY');
+        logger.log('='.repeat(120));
+        logger.log(`Total Events: ${totalEvents}`);
+        logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+        logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+        logger.log(`Average per week: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
+        logger.log('='.repeat(120) + '\n');
+        // Show breakdown if requested
+        if (options.breakdown) {
+            displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+        }
+    }
 }
 /**
  * Show usage for a specific date
@@ -234,40 +243,43 @@ export async function showDateReport(credentials, date, options = {}, outputJson
         logger.warn('No usage events found for this date');
         return;
     }
-    logger.log('');
-    // Display detailed events
-    logger.log('\n' + '='.repeat(120));
-    logger.log(`USAGE EVENTS FOR ${date.toDateString()}`);
-    logger.log('='.repeat(120) + '\n');
-    const tableData = events.map((event) => {
-        const timestamp = new Date(event.timestamp).toLocaleTimeString();
-        return [
-            timestamp,
-            event.model,
-            event.type,
-            event.inputTokens.toLocaleString(),
-            event.outputTokens.toLocaleString(),
-            event.tokens.toLocaleString(),
-            `$${event.cost?.toFixed(4) || '0.0000'}`,
-        ];
-    });
-    const table = createTable(['Time', 'Model', 'Type', 'Input Tokens', 'Output Tokens', 'Total Tokens', 'Cost'], tableData);
-    logger.log(table);
-    // Summary
-    const totalTokens = events.reduce((sum, e) => sum + e.tokens, 0);
-    const totalCost = events.reduce((sum, e) => sum + (e.cost || 0), 0);
-    logger.log('\n' + '='.repeat(120));
-    logger.log(`Total Events: ${events.length}`);
-    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
-    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
-    logger.log('='.repeat(120) + '\n');
-    // Show breakdown if requested
-    if (options.breakdown) {
-        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
-    }
-    // Output JSON if requested
     if (outputJson) {
+        // Output JSON only - no table display
         const jsonOutput = statsToJSON('today', events.map((e, i) => ({ ...e, eventIndex: i })), events, { breakdown: options.breakdown, period: 'today' });
         console.log(jsonOutput);
     }
+    else {
+        // Display table and summary
+        logger.log('');
+        // Display detailed events
+        logger.log('\n' + '='.repeat(120));
+        logger.log(`USAGE EVENTS FOR ${date.toDateString()}`);
+        logger.log('='.repeat(120) + '\n');
+        const tableData = events.map((event) => {
+            const timestamp = new Date(event.timestamp).toLocaleTimeString();
+            return [
+                timestamp,
+                event.model,
+                event.type,
+                event.inputTokens.toLocaleString(),
+                event.outputTokens.toLocaleString(),
+                event.tokens.toLocaleString(),
+                `$${event.cost?.toFixed(4) || '0.0000'}`,
+            ];
+        });
+        const table = createTable(['Time', 'Model', 'Type', 'Input Tokens', 'Output Tokens', 'Total Tokens', 'Cost'], tableData);
+        logger.log(table);
+        // Summary
+        const totalTokens = events.reduce((sum, e) => sum + e.tokens, 0);
+        const totalCost = events.reduce((sum, e) => sum + (e.cost || 0), 0);
+        logger.log('\n' + '='.repeat(120));
+        logger.log(`Total Events: ${events.length}`);
+        logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+        logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+        logger.log('='.repeat(120) + '\n');
+        // Show breakdown if requested
+        if (options.breakdown) {
+            displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+        }
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursor-usage",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI tool for analyzing Cursor usage and token consumption",
   "author": "yifen <anthonyeef@gmail.com>",
   "license": "MIT",