Command-Line Options

ccusage provides extensive command-line options to customize its behavior. These options take precedence over configuration files and environment variables.

Global Options

All ccusage commands support these global options:

Date Filtering

Filter usage data by date range:

# Filter by date range
ccusage daily --since 20260101 --until 20260531

# Show data from a specific date
ccusage monthly --since 20260101

# Show data up to a specific date
ccusage session --until 20260531

Both bounds accept YYYY-MM-DD or YYYYMMDD and are inclusive. Any other spelling, or a value that is not a real calendar date such as 2026-02-30, is rejected with a non-zero exit code instead of silently changing which rows the report keeps. The same check applies to since and until in a configuration file. A window whose --since date is later than its --until date is rejected the same way, whether the bounds come from flags, a configuration file, or a mix of both. statusline is exempt because it ignores report date filters, including configured defaults.

Recent Periods

Instead of working out dates, ask for the most recent periods of whatever the report groups by:

# Today
ccusage daily --last 1

# This week
ccusage weekly --last 1

# This month
ccusage monthly --last 1

# The last seven days, and the last three months
ccusage daily --last 7
ccusage monthly --last 3

The count is inclusive of the current period, so --last 2 on a daily report covers yesterday and today. Weeks start on the same day the report buckets by, which is Monday everywhere except ccusage claude weekly, where --start-of-week decides.

--last works on every daily, weekly, and monthly report, including the per-agent ones such as ccusage codex daily --last 1. It is not available on session, blocks, or statusline, which have no calendar period, and it cannot be combined with --since, --until, or --sections.

Output Format

Control how data is displayed:

# JSON output for programmatic use
ccusage daily --json
ccusage daily -j

# Show per-model breakdown
ccusage daily --breakdown
ccusage daily -b

# Hide cost columns and JSON cost fields
ccusage daily --no-cost
ccusage daily --json --no-cost

# Combine options
ccusage daily --json --breakdown

--no-cost removes cost columns from table output and removes cost fields such as totalCost, costUSD, and cost from JSON output.

Cost Calculation Mode

Choose how costs are calculated:

# Auto mode (default) - use costUSD when available
ccusage daily --mode auto

# Calculate mode - always calculate from tokens
ccusage daily --mode calculate

# Display mode - only show pre-calculated costUSD
ccusage daily --mode display

Sort Order

Control the ordering of results:

# Newest first (default)
ccusage daily --order desc

# Oldest first
ccusage daily --order asc

Offline Mode

Run without network connectivity:

# Use cached pricing data
ccusage daily --offline
ccusage daily -O

Timezone

Set the timezone for date calculations:

# Use UTC timezone
ccusage daily --timezone UTC

# Use specific timezone
ccusage daily --timezone America/New_York
ccusage daily -z Asia/Tokyo

# Short alias
ccusage monthly -z Europe/London

The value must be UTC, another IANA timezone name, or local for the system timezone. An unknown name such as Not/AZone is rejected with a non-zero exit code instead of silently falling back to the system timezone, which can group usage under the wrong date. The same check applies to timezone in a configuration file.

Timezone Effect

The timezone affects how usage is grouped by date. For example, usage at 11 PM UTC on January 1st would appear on:

• January 1st when --timezone UTC
• January 1st when --timezone America/New_York (6 PM EST)
• January 2nd when --timezone Asia/Tokyo (8 AM JST next day)

Debug Options

Get detailed debugging information:

# Debug mode - show pricing mismatches and config loading
ccusage daily --debug

# Show sample discrepancies
ccusage daily --debug --debug-samples 10

Configuration File

Use a custom configuration file:

# Specify custom config file
ccusage daily --config ./my-config.json
ccusage monthly --config /path/to/team-config.json

Command-Specific Options

Unified Report Options

These options apply to ccusage daily, ccusage weekly, ccusage monthly, and ccusage session when they are aggregating all detected sources:

# Emit several JSON report sections from one source load
ccusage daily --sections daily,monthly,session --json

# Add per-agent breakdowns to daily, weekly, and monthly JSON rows
ccusage daily --by-agent --json

--sections accepts a comma-separated list of daily, weekly, monthly, and session. The invoked report section is always included. For table output, each requested section is printed as a separate table. --by-agent is JSON-only; session rows are already per-agent.

Daily Command

Additional options for daily reports:

# Group by project
ccusage daily --instances
ccusage daily -i

# Filter to specific project
ccusage daily --project myproject
ccusage daily -p myproject

# Combine project filtering
ccusage daily --instances --project myproject

Weekly Command

Options for weekly reports:

# Set week start day
ccusage weekly --start-of-week monday
ccusage weekly --start-of-week sunday

Session Command

Options for session reports:

# Filter by session ID
ccusage session --id abc123-session

# Filter by project
ccusage session --project myproject

Blocks Command

Options for 5-hour billing blocks:

# Show only active block
ccusage blocks --active
ccusage blocks -a

# Show recent blocks (last 3 days)
ccusage blocks --recent
ccusage blocks -r

# Set token limit for warnings
ccusage blocks --token-limit 500000
ccusage blocks --token-limit max

# Live monitoring mode
ccusage blocks --live
ccusage blocks --live --refresh-interval 2

# Customize session length
ccusage blocks --session-length 5

Statusline

Options for statusline display:

# Basic statusline
ccusage statusline

# Force offline mode
ccusage statusline --offline

# Enable caching
ccusage statusline --cache

# Custom refresh interval
ccusage statusline --refresh-interval 5

JSON Output

# Print JSON output
ccusage daily --json

# Print JSON without cost fields
ccusage daily --json --no-cost

# Pipe JSON output to jq
ccusage daily --json | jq ".data[]"

# Extract specific fields
ccusage session --json | jq ".data[] | {date, cost}"

Option Precedence

Options are applied in this order (highest to lowest priority):

1. Command-line arguments - Direct CLI options
2. Custom config file - Via --config flag
3. Local project config - .ccusage/ccusage.json
4. User config - ~/.config/claude/ccusage.json
5. Legacy config - ~/.claude/ccusage.json
6. Built-in defaults

Examples

Development Workflow

# Daily development check
ccusage daily --instances --breakdown

# Check specific project costs
ccusage daily --project myapp --since 20260101

# Export for reporting
ccusage monthly --json > monthly-report.json

Team Collaboration

# Use team configuration
ccusage daily --config ./team-config.json

# Consistent timezone for remote team
ccusage daily --timezone UTC

# Generate shareable report
ccusage weekly --json

Cost Monitoring

# Monitor active usage
ccusage blocks --active --live

# Check if approaching limits
ccusage blocks --token-limit 500000

# Historical analysis
ccusage monthly --mode calculate --breakdown

Debugging Issues

# Debug configuration loading
ccusage daily --debug --config ./test-config.json

# Check pricing discrepancies
ccusage daily --debug --debug-samples 20

# Silent mode for scripts
LOG_LEVEL=0 ccusage daily --json

Short Aliases

Many options have short aliases for convenience:

Long Option	Short	Description
--json	-j	JSON output
--breakdown	-b	Per-model breakdown
--offline	-O	Offline mode
--timezone	-z	Set timezone
--instances	-i	Group by project
--project	-p	Filter project
--active	-a	Active block only
--recent	-r	Recent blocks

Related Documentation

• Environment Variables - Configure via environment
• Configuration Files - Persistent configuration
• Cost Calculation Modes - Understanding cost modes