id          = "ccusage"
name        = "ccusage"
homepage    = "https://github.com/ccusage/ccusage"
description = "A CLI tool for analyzing Claude Code usage from local JSONL files."
executables      = ["ccusage"]

[dotfiles]

# ccusage's official configuration guide lists the user config and its legacy
# user config, while .ccusage/ is explicitly project-local:
# https://github.com/ccusage/ccusage/blob/main/docs/guide/configuration.md
paths = [
  "~/.config/claude/ccusage.json",
  "~/.claude/ccusage.json",
]
secret = []
side_effect = false

[commands]
format = 1
label = "Usage report"
description = "Report Claude Code (and other coding CLI) token usage and cost by day, week, month or session. Blocks, statusline, per-agent namespaces and config-file options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "docs"
kind = "manual"
url = "https://github.com/ccusage/ccusage/blob/main/docs/guide/cli-options.md"
revision = "2026-10-27"
evidence = """
ccusage daily --since 20260101 --until 20260531
ccusage monthly --since 20260101
ccusage session --until 20260531
ccusage weekly --last 1
ccusage daily --json
ccusage daily -j
ccusage daily --breakdown
ccusage daily -b
ccusage daily --no-cost
ccusage daily --mode auto
ccusage daily --mode calculate
ccusage daily --mode display
ccusage daily --order desc
ccusage daily --order asc
ccusage daily --offline
ccusage daily -O
ccusage daily -z Asia/Tokyo
ccusage daily --timezone America/New_York
ccusage daily --instances
ccusage daily -i
ccusage daily --project myproject
ccusage daily -p myproject
"""

[[commands.field]]
id = "report"
label = "Report"
description = "Which grouping to report."
type = "enum"
position = 0
choices = [{ value = "daily", label = "Daily" }, { value = "weekly", label = "Weekly" }, { value = "monthly", label = "Monthly" }, { value = "session", label = "Session" }]
sources = ["docs"]

[[commands.field]]
id = "since"
label = "Since"
description = "Inclusive start date, YYYY-MM-DD or YYYYMMDD."
type = "string"
option = ["--since"]
sources = ["docs"]

[[commands.field]]
id = "until"
label = "Until"
description = "Inclusive end date, YYYY-MM-DD or YYYYMMDD."
type = "string"
option = ["--until"]
sources = ["docs"]

[[commands.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json", "-j"]
sources = ["docs"]

[[commands.field]]
id = "breakdown"
label = "Per-model breakdown"
type = "boolean"
option = ["--breakdown", "-b"]
sources = ["docs"]

[[commands.field]]
id = "no_cost"
label = "Hide cost"
type = "boolean"
option = ["--no-cost"]
sources = ["docs"]

[[commands.field]]
id = "order"
label = "Sort order"
type = "enum"
option = ["--order"]
choices = [{ value = "desc", label = "Newest first" }, { value = "asc", label = "Oldest first" }]
sources = ["docs"]

[[commands.field]]
id = "mode"
label = "Cost mode"
type = "enum"
option = ["--mode"]
choices = [{ value = "auto", label = "Auto" }, { value = "calculate", label = "Calculate from tokens" }, { value = "display", label = "Pre-calculated only" }]
sources = ["docs"]

[[commands.field]]
id = "offline"
label = "Offline"
description = "Use cached pricing data."
type = "boolean"
option = ["--offline", "-O"]
sources = ["docs"]

[[commands.field]]
id = "timezone"
label = "Timezone"
type = "string"
option = ["--timezone", "-z"]
suggestions = [{ value = "UTC", label = "UTC" }, { value = "local", label = "System" }, { value = "America/New_York", label = "New York" }, { value = "Asia/Tokyo", label = "Tokyo" }]
sources = ["docs"]

[[commands.field]]
id = "instances"
label = "Group by project"
description = "Daily report only."
type = "boolean"
option = ["--instances", "-i"]
sources = ["docs"]

[[commands.field]]
id = "project"
label = "Project"
description = "Daily report only."
type = "string"
option = ["--project", "-p"]
sources = ["docs"]

[[commands.task]]
id = "daily"
label = "Daily usage"
set = { report = ["daily"] }
lock = ["report"]
fields = ["report", "since", "until", "breakdown", "instances", "project", "order", "offline"]
required = ["report"]

[[commands.task]]
id = "monthly-json"
label = "Monthly JSON"
set = { report = ["monthly"], json = [true] }
lock = ["report", "json"]
fields = ["report", "json", "since", "until", "timezone"]
required = ["report"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["report", "since", "until", "json", "breakdown", "order"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["no_cost", "mode", "offline", "timezone", "instances", "project"]