Skip to main content

​
Overview

The monthly command displays Claude Code usage statistics aggregated by month. It shows token usage (input, output, cache creation, and cache read tokens), costs, and models used for each month.

​
Usage

ccusage monthly

​
Flags

​
Common Flags

​
--since
string
Filter from date in YYYYMMDD format (e.g., 20240101).Short flag: -s
​
--until
string
Filter until date in YYYYMMDD format (e.g., 20241231).Short flag: -u
​
--json
boolean
default:"false"
Output in JSON format instead of a formatted table.Short flag: -j
​
--jq
string
Process JSON output with jq command. Requires jq binary installed. Implies —json.Short flag: -qExample: ccusage monthly --jq '.monthly[] | select(.totalCost > 10.0)'
​
--mode
enum
default:"auto"
Cost calculation mode:
  • auto: Use costUSD if exists, otherwise calculate from tokens
  • calculate: Always calculate costs from token counts
  • display: Always use pre-calculated costUSD values
Short flag: -mChoices: auto, calculate, display
​
--breakdown
boolean
default:"false"
Show per-model cost breakdown. Displays detailed token usage for each model used.Short flag: -b
​
--offline
boolean
default:"false"
Use cached pricing data for Claude models instead of fetching from API.Short flag: -ONegatable: Use --no-offline to disable
​
--order
enum
default:"asc"
Sort order:
  • asc: Oldest first
  • desc: Newest first
Short flag: -oChoices: asc, desc
​
--debug
boolean
default:"false"
Show pricing mismatch information for debugging.Short flag: -d
​
--debug-samples
number
default:"5"
Number of sample discrepancies to show in debug output.
​
--timezone
string
Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone.Short flag: -z
​
--locale
string
default:"en-US"
Locale for date/time formatting (e.g., en-US, ja-JP, de-DE).Short flag: -l
​
--compact
boolean
default:"false"
Force compact mode for narrow displays (better for screenshots).
​
--config
string
Path to configuration file. Default: auto-discovery.
​
--color
boolean
Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.
​
--no-color
boolean
Disable colored output (default: auto). NO_COLOR=1 has the same effect.

​
Output Formats

​
Table Output (Default)

Displays a formatted table with columns:
  • Month: Month in YYYY-MM format
  • Input: Input tokens
  • Output: Output tokens
  • Cache Creation: Cache creation tokens
  • Cache Read: Cache read tokens
  • Total: Total tokens
  • Cost: Total cost in USD
  • Models: Models used that month
Includes a totals row at the bottom.
In narrow terminals or with --compact flag, some columns (cache metrics and total tokens) may be hidden. A message will indicate compact mode is active.

​
JSON Output

With --json flag, outputs structured JSON: 
{
  "monthly": [
    {
      "month": "2024-03",
      "inputTokens": 3500000,
      "outputTokens": 450000,
      "cacheCreationTokens": 1200000,
      "cacheReadTokens": 300000,
      "totalTokens": 5450000,
      "totalCost": 25.50,
      "modelsUsed": ["claude-sonnet-4-20250514", "claude-opus-4-20250514"],
      "modelBreakdowns": [
        {
          "model": "claude-sonnet-4-20250514",
          "inputTokens": 3000000,
          "outputTokens": 400000,
          "cacheCreationTokens": 1000000,
          "cacheReadTokens": 250000,
          "totalCost": 22.00
        },
        {
          "model": "claude-opus-4-20250514",
          "inputTokens": 500000,
          "outputTokens": 50000,
          "cacheCreationTokens": 200000,
          "cacheReadTokens": 50000,
          "totalCost": 3.50
        }
      ]
    }
  ],
  "totals": {
    "inputTokens": 3500000,
    "outputTokens": 450000,
    "cacheCreationTokens": 1200000,
    "cacheReadTokens": 300000,
    "totalTokens": 5450000,
    "totalCost": 25.50
  }
}

​
Examples

​
View all monthly usage

ccusage monthly

​
View 2024 usage only

ccusage monthly --since 20240101 --until 20241231

​
Export monthly data to JSON

ccusage monthly --json > monthly-usage.json

​
Show detailed model breakdown

ccusage monthly --breakdown

​
Find months exceeding $10

ccusage monthly --jq '.monthly[] | select(.totalCost > 10)'

​
Calculate costs from tokens (ignore pre-calculated)

ccusage monthly --mode calculate
  • daily - View usage grouped by day
  • weekly - View usage grouped by week
  • session - View usage by session
  • blocks - View usage by 5-hour billing blocks

Build docs developers (and LLMs) love

Get started for freeTalk to us