命令行

CLI 的全部能力。

十个子命令：前台或后台跑仪表盘、不起服务直接打终端报告、以 stdio 提供 MCP 服务、或者诊断一个装坏了的环境。它们读的都是同一份本地 JSONL。

子命令

命令	作用
ccgauge	前台启动仪表盘并打开浏览器，等价于 `ccgauge start`。
ccgauge start -b	以后台服务方式常驻，状态和日志写在 `~/.ccgauge/`。
ccgauge stop [--force]	停止后台服务，优雅停或强杀。
ccgauge restart	重启后台服务，接受与 `start` 相同的参数。
ccgauge status [--json]	PID / URL / 运行时长。没起来时退出码 3（systemd 风格的「未运行」）。
ccgauge open	在浏览器里打开已经跑着的仪表盘。
ccgauge logs [-f]	跟踪后台服务日志。
ccgauge report	一次性终端报告，不起服务。完整说明见下。
ccgauge mcp	以 stdio 启动 MCP 服务，让 LLM 直接查你的用量。
ccgauge doctor	一屏诊断：版本、环境、构建产物、服务状态、各数据源扫描结果。报 bug 时直接贴。

格式化的、无 server 的终端用量报告，0.2 秒出结果。加 -d 得到一屏 TUI 看板 —— KPI tile、堆叠趋势图、breakdown 表格、7×24 活跃热力图 —— 窗口宽度不足 80 列时自动回退纯文本。--json 走管道接你的脚本。

默认：近 7 天，全部数据源，前 10 个模型

bash

ccgauge report

30 天 + 按项目分组

bash

ccgauge report -r 30d -b project

只看 Codex 的 gpt-5.5 系列

bash

ccgauge report -s codex -m gpt-5.5

JSON 输出给脚本用

bash

ccgauge report --json | jq .totals

任意日期区间

bash

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

极简：只看总数

bash

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

一屏 TUI 看板

bash

ccgauge report -d

起后台服务并查看状态

bash

ccgauge start -b && ccgauge status

参数	默认	作用
`-r, --range <range>`	7d	`today` / `1d` / `7d` / `30d` / `90d` / `all`
`-s, --source <provider>`	all	`claude` / `codex` / `all`
`-b, --by <dim>`	model	分组维度：`model` / `project` / `session`
`-g, --gran <granularity>`	day	趋势粒度：`hour` / `day` / `week` / `month`
`-n, --limit <n>`	10	分组表行数
`--since <date>`	—	自定义起始日期（ISO 或 `YYYY-MM-DD`）
`--until <date>`	—	自定义截止日期
`-m, --model <pat>`	—	按模型名子串过滤
`--project <pat>`	—	按项目名 / cwd 子串过滤
`-j, --json`	off	输出 JSON 而不是格式化文本
`--no-color`	—	关闭 ANSI 颜色（管道里自动关）
`--no-trend`	—	不打趋势图
`--no-breakdown`	—	不打分组表
`-d, --dashboard`	off	一屏富 TUI：KPI tile、堆叠趋势图、双列 breakdown、7×24 热力图
`--width <n>`	tty 列数	强制输出宽度 —— 截图和 CI 日志好用
`--no-banner`	—	仅 dashboard：跳过顶部 banner 行
`--compact`	—	仅 dashboard：跳过趋势图，省纵向空间