CLI

ccgauge report

A formatted, no-server terminal usage report. Reads the same JSONL the dashboard reads, then prints a colored aligned summary in ~0.2 s. Use it locally to spot-check yesterday's spend, or pipe --json into your own scripts.

Quick examples

Default — last 7 days, all sources, top 10 models

bash

ccgauge report

30 days, broken down by project

bash

ccgauge report -r 30d -b project

Codex only, gpt-5.5 family

bash

ccgauge report -s codex -m gpt-5.5

JSON output for piping into scripts

bash

ccgauge report --json | jq .totals

Arbitrary date range

bash

ccgauge report --since 2026-05-01 --until 2026-05-08

Minimal — just totals, no chart or breakdown

bash

ccgauge report --no-trend --no-breakdown

Flag reference

Flag	Default	Purpose
`-r, --range <range>`	7d	`today` / `1d` / `7d` / `30d` / `90d` / `all`
`-s, --source <provider>`	all	`claude` / `codex` / `all`
`-b, --by <dim>`	model	Breakdown dimension: `model` / `project` / `session`
`-g, --gran <granularity>`	day	Trend bucket: `hour` / `day` / `week` / `month`
`-n, --limit <n>`	10	Rows in the breakdown table
`--since <date>`	—	Override range start (ISO date or `YYYY-MM-DD`)
`--until <date>`	—	Override range end
`-m, --model <pat>`	—	Filter records whose model contains
`--project <pat>`	—	Filter by project basename / cwd substring
`-j, --json`	off	Machine-readable JSON instead of formatted text
`--no-color`	—	Disable ANSI colors (auto-disabled when piped)
`--no-trend`	—	Skip the trend chart
`--no-breakdown`	—	Skip the breakdown table

Tips

Date-only --since/--until use local calendar-day boundaries. --until 2026-05-08 includes all of May 8.
No server is started. The report runs against the on-disk JSONL files directly, then exits as soon as stdout is drained. Safe to call from CI.
Colors auto-disable when stdout isn't a TTY. You don't need to pass --no-color for piped output.
JSON output includes totals, trend, and breakdown arrays. Stable shape; safe to consume from scripts.

← Back to features