Skip to main content

​
Overview

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

​
Usage

ccusage weekly

​
Flags

​
Command-Specific Flags

​
--start-of-week
enum
default:"sunday"
Day to start the week on. Determines how usage data is grouped into weekly periods.Short flag: -wChoices: sunday, monday, tuesday, wednesday, thursday, friday, saturday

​
Common Flags

​
--since
string
Filter from date in YYYYMMDD format (e.g., 20240301).Short flag: -s
​
--until
string
Filter until date in YYYYMMDD format (e.g., 20240331).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 weekly --jq '.weekly[] | select(.totalCost > 5.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:
  • Week: Week start date in YYYY-MM-DD 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 week
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: 
{
  "weekly": [
    {
      "week": "2024-03-03",
      "inputTokens": 850000,
      "outputTokens": 110000,
      "cacheCreationTokens": 300000,
      "cacheReadTokens": 75000,
      "totalTokens": 1335000,
      "totalCost": 6.25,
      "modelsUsed": ["claude-sonnet-4-20250514"],
      "modelBreakdowns": [
        {
          "model": "claude-sonnet-4-20250514",
          "inputTokens": 850000,
          "outputTokens": 110000,
          "cacheCreationTokens": 300000,
          "cacheReadTokens": 75000,
          "totalCost": 6.25
        }
      ]
    }
  ],
  "totals": {
    "inputTokens": 850000,
    "outputTokens": 110000,
    "cacheCreationTokens": 300000,
    "cacheReadTokens": 75000,
    "totalTokens": 1335000,
    "totalCost": 6.25
  }
}

​
Examples

​
View weekly usage (Sunday start)

ccusage weekly

​
View weekly usage (Monday start)

ccusage weekly --start-of-week monday

​
View March 2024 by week

ccusage weekly --since 20240301 --until 20240331

​
Export weekly data to JSON

ccusage weekly --json > weekly-usage.json

​
Show detailed model breakdown

ccusage weekly --breakdown

​
Filter expensive weeks using jq

ccusage weekly --jq '.weekly[] | select(.totalCost > 5)'
  • daily - View usage grouped by day
  • monthly - View usage grouped by month
  • 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