Gemini CLI usage statistics
npm install gcusageUsage report for Gemini CLI
- Reads ~/.gemini/telemetry.log and summarizes token usage
- Only counts the final cumulative value for each session
- Supports day/week/month/session views
- Supports log trimming (keep only token-related data)
Enable telemetry in ~/.gemini/settings.json and set an absolute path:
``json`
{
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "",
"outfile": "/Users/
"logPrompts": false
}
}
Notes:
- Telemetry must be enabled and outfile set, otherwise telemetry.log will not be created~
- Use an absolute path to avoid failures caused by or relative pathsoutfile
- must match the path gcusage reads (default ~/.gemini/telemetry.log)trim
- The log contains full response content; use to shrink itC:\\Users\\
- Windows example path:
Published version: gcusage@0.1.4
npm package page: https://www.npmjs.com/package/gcusage
- Supported: macOS / Linux / Windows
Default output shows daily stats for the last 6 days (including today):
`bash`
npx gcusage
Output: one line per day, showing the Models column (wraps for multiple models) and totals by token type.
Per-session output (one line per session for today):
`bash`
npx gcusage --period session
Output: final cumulative value for each session for today.
Weekly view (shows each day in the week):
`bash`
npx gcusage --period week
Output: daily data for the current week (week starts on Monday).
Monthly view (shows each day in the month):
`bash`
npx gcusage --period month
Output: daily data for the current month.
Start a week from a specific date:
`bash`
npx gcusage --period week --since 2026-01-01
Output: 7 days starting from 2026-01-01.
Specify a custom range (overrides week/month ranges):
`bash`
npx gcusage --period month --since 2026-01-01 --until 2026-01-15
Output: daily data from 2026-01-01 to 2026-01-15.
Filter by model or type:
`bash`
npx gcusage --model gemini-2.5-flash-lite --type input
Output: only counts the specified model and token type.
Header:
``
Date | Models | Input | Output | Thought | Cache | Tool | Total Tokens
Notes:
- Multiple models are shown on separate lines
- Numbers use thousands separators
- Total row uses k/M/B abbreviations with two decimals
- Header/title in cyan-blue; Total row in gold
- Title and date range shown above the table
Keep only token-related data (overwrites original file):
`bash`
npx gcusage trim
Output: telemetry.log becomes much smaller; statistics are unchanged.
Notes:
- Backs up to telemetry.log.bak`, then removes the backup on success
- Keeps only the last cumulative value per session+model+type