ccusage

{ "$ref": "#/definitions/ccusage-config", "definitions": { "ccusage-config": { "type": "object", "properties": { "$schema": { "type": "string", "description": "JSON Schema URL for validation and autocomplete", "markdownDescription": "JSON Schema URL for validation and autocomplete" }, "defaults": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order: desc (newest first) or asc (oldest first)", "markdownDescription": "Sort order: desc (newest first) or asc (oldest first)", "default": "asc" }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false } }, "additionalProperties": false, "description": "Default values for all commands", "markdownDescription": "Default values for all commands" }, "commands": { "type": "object", "properties": { "daily": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order: desc (newest first) or asc (oldest first)", "markdownDescription": "Sort order: desc (newest first) or asc (oldest first)", "default": "asc" }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false }, "instances": { "type": "boolean", "description": "Show usage breakdown by project/instance", "markdownDescription": "Show usage breakdown by project/instance", "default": false }, "project": { "type": "string", "description": "Filter to specific project name", "markdownDescription": "Filter to specific project name" }, "projectAliases": { "type": "string", "description": "Comma-separated project aliases (e.g., 'ccusage=Usage Tracker,myproject=My Project')", "markdownDescription": "Comma-separated project aliases (e.g., 'ccusage=Usage Tracker,myproject=My Project')" } }, "additionalProperties": false }, "monthly": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order: desc (newest first) or asc (oldest first)", "markdownDescription": "Sort order: desc (newest first) or asc (oldest first)", "default": "asc" }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false } }, "additionalProperties": false }, "weekly": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order: desc (newest first) or asc (oldest first)", "markdownDescription": "Sort order: desc (newest first) or asc (oldest first)", "default": "asc" }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false }, "startOfWeek": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "description": "Day to start the week on", "markdownDescription": "Day to start the week on", "default": "sunday" } }, "additionalProperties": false }, "session": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false }, "id": { "type": "string", "description": "Load usage data for a specific session ID", "markdownDescription": "Load usage data for a specific session ID" } }, "additionalProperties": false }, "blocks": { "type": "object", "properties": { "since": { "type": "string", "description": "Filter from date (YYYYMMDD format)", "markdownDescription": "Filter from date (YYYYMMDD format)" }, "until": { "type": "string", "description": "Filter until date (YYYYMMDD format)", "markdownDescription": "Filter until date (YYYYMMDD format)" }, "json": { "type": "boolean", "description": "Output in JSON format", "markdownDescription": "Output in JSON format", "default": false }, "mode": { "type": "string", "enum": [ "auto", "calculate", "display" ], "description": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "markdownDescription": "Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)", "default": "auto" }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false }, "debugSamples": { "type": "number", "description": "Number of sample discrepancies to show in debug output (default: 5)", "markdownDescription": "Number of sample discrepancies to show in debug output (default: 5)", "default": 5 }, "order": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order: desc (newest first) or asc (oldest first)", "markdownDescription": "Sort order: desc (newest first) or asc (oldest first)", "default": "asc" }, "breakdown": { "type": "boolean", "description": "Show per-model cost breakdown", "markdownDescription": "Show per-model cost breakdown", "default": false }, "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": false }, "color": { "type": "boolean", "description": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.", "markdownDescription": "Enable colored output (default: auto). FORCE_COLOR=1 has the same effect." }, "noColor": { "type": "boolean", "description": "Disable colored output (default: auto). NO_COLOR=1 has the same effect.", "markdownDescription": "Disable colored output (default: auto). NO_COLOR=1 has the same effect." }, "timezone": { "type": "string", "description": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone", "markdownDescription": "Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone" }, "locale": { "type": "string", "description": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "markdownDescription": "Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)", "default": "en-CA" }, "jq": { "type": "string", "description": "Process JSON output with jq command (requires jq binary, implies --json)", "markdownDescription": "Process JSON output with jq command (requires jq binary, implies --json)" }, "compact": { "type": "boolean", "description": "Force compact mode for narrow displays (better for screenshots)", "markdownDescription": "Force compact mode for narrow displays (better for screenshots)", "default": false }, "active": { "type": "boolean", "description": "Show only active block with projections", "markdownDescription": "Show only active block with projections", "default": false }, "recent": { "type": "boolean", "description": "Show blocks from last 3 days (including active)", "markdownDescription": "Show blocks from last 3 days (including active)", "default": false }, "tokenLimit": { "type": "string", "description": "Token limit for quota warnings (e.g., 500000 or \"max\")", "markdownDescription": "Token limit for quota warnings (e.g., 500000 or \"max\")" }, "sessionLength": { "type": "number", "description": "Session block duration in hours (default: 5)", "markdownDescription": "Session block duration in hours (default: 5)", "default": 5 } }, "additionalProperties": false }, "statusline": { "type": "object", "properties": { "offline": { "type": "boolean", "description": "Use cached pricing data for Claude models instead of fetching from API", "markdownDescription": "Use cached pricing data for Claude models instead of fetching from API", "default": true }, "visualBurnRate": { "type": "string", "enum": [ "off", "emoji", "text", "emoji-text" ], "description": "Controls the visualization of the burn rate status", "markdownDescription": "Controls the visualization of the burn rate status", "default": "off" }, "costSource": { "type": "string", "enum": [ "auto", "ccusage", "cc", "both" ], "description": "Session cost source: auto (prefer CC then ccusage), ccusage (always calculate), cc (always use Claude Code cost), both (show both costs)", "markdownDescription": "Session cost source: auto (prefer CC then ccusage), ccusage (always calculate), cc (always use Claude Code cost), both (show both costs)", "default": "auto" }, "cache": { "type": "boolean", "description": "Enable cache for status line output (default: true)", "markdownDescription": "Enable cache for status line output (default: true)", "default": true }, "refreshInterval": { "type": "number", "description": "Refresh interval in seconds for cache expiry (default: 1)", "markdownDescription": "Refresh interval in seconds for cache expiry (default: 1)", "default": 1 }, "contextLowThreshold": { "type": "string", "description": "Context usage percentage below which status is shown in green (0-100)", "markdownDescription": "Context usage percentage below which status is shown in green (0-100)", "default": 50 }, "contextMediumThreshold": { "type": "string", "description": "Context usage percentage below which status is shown in yellow (0-100)", "markdownDescription": "Context usage percentage below which status is shown in yellow (0-100)", "default": 80 }, "debug": { "type": "boolean", "description": "Show pricing mismatch information for debugging", "markdownDescription": "Show pricing mismatch information for debugging", "default": false } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Command-specific configuration overrides", "markdownDescription": "Command-specific configuration overrides" } }, "additionalProperties": false } }, "$schema": "https://json-schema.org/draft-07/schema#", "title": "ccusage Configuration", "description": "Configuration file for ccusage - Claude Code usage analysis tool", "examples": [ { "$schema": "https://ccusage.com/config-schema.json", "defaults": { "json": false, "mode": "auto", "timezone": "Asia/Tokyo", "locale": "ja-JP" }, "commands": { "daily": { "instances": true }, "blocks": { "tokenLimit": "500000" } } } ] }