Skip to main content

​
Your first report

Run your first usage report with the default daily view: 
npx ccusage@latest
This displays a daily token usage report with:
  • Date-by-date breakdown of token usage
  • Input, output, cache creation, and cache read tokens
  • Total costs in USD
  • Models used for each day

​
Basic commands

ccusage provides several report types to analyze your usage:
1

Daily report

View token usage and costs aggregated by date:
npx ccusage daily
This is the default command when you run ccusage without arguments.
2

Monthly report

View token usage and costs aggregated by month:
npx ccusage monthly
Perfect for understanding your long-term usage patterns.
3

Session report

View usage grouped by conversation sessions:
npx ccusage session
Ideal for tracking costs per project or conversation.
4

5-hour blocks

Track usage within Claude’s billing windows:
npx ccusage blocks
Shows your usage in 5-hour billing cycles with active block monitoring.

​
Common options

​
Filter by date range

Filter reports to a specific date range using --since and --until: 
# View usage from May 25 to May 30, 2025
npx ccusage daily --since 20250525 --until 20250530
Date filters use YYYYMMDD format (e.g., 20250525 for May 25, 2025).

​
JSON output

Export data in JSON format for programmatic consumption: 
npx ccusage daily --json
Example output: 
{
  "daily": [
    {
      "date": "2025-05-25",
      "inputTokens": 15234,
      "outputTokens": 8912,
      "cacheCreationTokens": 2341,
      "cacheReadTokens": 4521,
      "totalTokens": 31008,
      "totalCost": 0.45,
      "modelsUsed": ["claude-sonnet-4-20250514"]
    }
  ],
  "totals": {
    "inputTokens": 15234,
    "outputTokens": 8912,
    "cacheCreationTokens": 2341,
    "cacheReadTokens": 4521,
    "totalTokens": 31008,
    "totalCost": 0.45
  }
}

​
Model breakdown

View per-model cost breakdown with the --breakdown flag: 
npx ccusage daily --breakdown
This adds additional rows showing token usage and costs for each model (e.g., Opus, Sonnet) separately.

​
Compact mode

Force compact table layout, perfect for narrow terminals or screenshots: 
npx ccusage daily --compact
ccusage automatically detects terminal width and switches to compact mode for terminals narrower than 100 characters.

​
Project analysis

​
Group by project

View usage breakdown by project or instance: 
npx ccusage daily --instances
This groups the report by project directories, making it easy to track costs per project.

​
Filter to specific project

Filter the report to a specific project: 
npx ccusage daily --project myproject
Combine with --instances for detailed project analysis: 
npx ccusage daily --instances --project myproject --json

​
Advanced options

​
Timezone configuration

Configure timezone for date grouping: 
npx ccusage daily --timezone UTC
npx ccusage daily --timezone America/New_York

​
Locale formatting

Customize date/time formatting with locale: 
npx ccusage daily --locale ja-JP
npx ccusage daily --locale de-DE

​
Offline mode

Use pre-cached pricing data without network connectivity (Claude models only): 
npx ccusage daily --offline

​
Statusline integration

ccusage includes a compact statusline mode for integration with Claude Code status bar hooks: 
npx ccusage statusline
The statusline feature is currently in Beta. It provides a compact usage display optimized for status bars.

​
Next steps

Daily reports

Learn more about daily usage reports and filtering options

Session tracking

Understand session-based usage analysis

MCP integration

Set up the MCP server for Claude Desktop integration

Configuration

Configure ccusage with JSON configuration files

Build docs developers (and LLMs) love

Get started for freeTalk to us