Skip to main content
ccusage supports JSON configuration files to set default options for all commands or specific commands. This eliminates the need to specify common flags repeatedly.

​
File Discovery

ccusage automatically searches for configuration files in the following locations (highest priority first):
  1. Local project config: .ccusage/ccusage.json in current directory
  2. User config directories: ccusage.json in Claude data directories
    • ~/.config/claude/ccusage.json (XDG config directory)
    • ~/.claude/ccusage.json (legacy directory)
    • Custom paths from CLAUDE_CONFIG_DIR environment variable
The first valid configuration file found is used. Lower priority locations are ignored.

​
File Format

Configuration files use JSON format with optional schema validation: 
{
  "$schema": "https://ccusage.com/config-schema.json",
  "defaults": {
    // Options applied to all commands
  },
  "commands": {
    "daily": {
      // Options specific to 'daily' command
    },
    "monthly": {
      // Options specific to 'monthly' command
    }
  }
}

​
Schema

​
$schema
string
Optional JSON schema URL for IDE validation and autocomplete.
{
  "$schema": "https://ccusage.com/config-schema.json"
}
​
defaults
object
Default options applied to all commands. Any CLI option can be set here.
{
  "defaults": {
    "mode": "calculate",
    "offline": true,
    "timezone": "UTC",
    "locale": "en-US"
  }
}
​
commands
object
Command-specific options that override defaults. Keys are command names (daily, monthly, session, blocks, statusline).
{
  "commands": {
    "daily": {
      "breakdown": true,
      "order": "desc"
    },
    "monthly": {
      "json": true
    }
  }
}

​
Priority Order

Options are merged with the following priority (highest to lowest):
  1. CLI arguments - Explicitly provided flags
  2. Command config - Command-specific settings in config file
  3. Defaults config - Default settings in config file
  4. Built-in defaults - Framework defaults
Only explicitly provided CLI arguments override config settings. Default values from argument definitions do not override config.

​
Examples

​
Development Configuration

For local development with offline mode and debugging:
.ccusage/ccusage.json
{
  "$schema": "https://ccusage.com/config-schema.json",
  "defaults": {
    "offline": true,
    "debug": true,
    "mode": "calculate",
    "timezone": "UTC"
  },
  "commands": {
    "daily": {
      "breakdown": true,
      "order": "desc"
    },
    "blocks": {
      "tokenLimit": 500000
    }
  }
}

​
Production Configuration

For production environments with JSON output:
~/.config/claude/ccusage.json
{
  "defaults": {
    "json": true,
    "noColor": true,
    "mode": "auto"
  },
  "commands": {
    "daily": {
      "order": "asc"
    },
    "monthly": {
      "breakdown": false
    }
  }
}

​
Timezone-Specific Configuration

For users in different timezones:
~/.claude/ccusage.json
{
  "defaults": {
    "timezone": "America/New_York",
    "locale": "en-US"
  },
  "commands": {
    "daily": {
      "breakdown": true
    }
  }
}

​
Minimal Configuration

Simple config with just a few common options:
.ccusage/ccusage.json
{
  "defaults": {
    "offline": true,
    "breakdown": true
  }
}

​
Using Custom Config Path

You can specify a custom configuration file location: 
# Use specific config file
ccusage daily --config /path/to/custom-config.json

# Debug mode to see which config is loaded
ccusage daily --debug

​
Validation

ccusage validates configuration files during loading:
  • Valid structure: Must be valid JSON with correct schema
  • Type checking: Options must have correct types (boolean, string, number)
  • Graceful errors: Invalid files are skipped with warnings
{
  "defaults": {
    "json": true,
    "mode": "auto"
  }
}

​
Available Options

All CLI options can be used in config files. Common options include:
  • json (boolean) - JSON output format
  • mode (string) - Cost calculation mode: auto, calculate, display
  • offline (boolean) - Use cached pricing data
  • breakdown (boolean) - Show per-model breakdown
  • order (string) - Sort order: asc, desc
  • timezone (string) - Timezone for date grouping
  • locale (string) - Locale for formatting
  • debug (boolean) - Enable debug output
  • debugSamples (number) - Number of debug samples
  • color (boolean) - Enable colored output
  • noColor (boolean) - Disable colored output
  • compact (boolean) - Compact display mode
See CLI Options for complete option documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us