Skip to content
ccgauge
EN 中
CLI

Everything the CLI does.

Ten subcommands: run the dashboard in the foreground or as a background service, print a terminal report without starting anything, serve MCP over stdio, or diagnose a bad install. All of them read the same local JSONL.

Subcommands

Command Purpose
ccgauge Start the dashboard in the foreground and open a browser. Alias of ccgauge start.
ccgauge start -b Run as a detached background service; state and logs land in ~/.ccgauge/.
ccgauge stop [--force] Stop the background service, gracefully or by force.
ccgauge restart Stop and start again, accepting the same options as start.
ccgauge status [--json] PID, URL, uptime. Exits 3 — systemd-style "not running" — when nothing is up.
ccgauge open Open the already-running dashboard in your browser.
ccgauge logs [-f] Tail the background-service log.
ccgauge report One-shot terminal report. No server. Documented in full below.
ccgauge mcp Start the MCP server on stdio so an LLM can query your usage.
ccgauge doctor One-screen diagnostic: version, env, build artifacts, service state, per-provider scan. Paste it into bug reports.

ccgauge report

A formatted, no-server terminal usage report in ~0.2 s. Add -d for a one-screen TUI dashboard — KPI tiles, stacked trend, breakdown tables and a 7×24 activity heatmap — which falls back to plain text below 80 columns. 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
Rich one-screen TUI dashboard
bash 
ccgauge report -d
Background service, then check on it
bash 
ccgauge start -b && ccgauge status

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
-d, --dashboard off Rich one-screen TUI: KPI tiles, stacked trend, double-column breakdown, 7×24 heatmap
--width <n> tty cols Force output width — useful for screenshots and CI logs
--no-banner — Dashboard only: skip the top banner row
--compact — Dashboard only: skip the trend chart to save vertical space

Tips

← Back to features