CLI reference · 04 macOS only

halton-meter report

Cost reports from the local SQLite store — by project, by model, with period comparison and CSV/JSON export. Layout adapts to terminal width.

macOS 12+ · Python 3.11+ Reading time 2 min Updated May 11, 2026

halton-meter report reads ~/.halton-meter/db.sqlite directly and prints a Rich-formatted cost report — by project, by model, or both — with optional period comparison and CSV/JSON export. The layout collapses columns based on terminal width so the report stays readable in a narrow split.

Synopsis

halton-meter report [--since|--from --to] [--by project|model] [--vs-previous] [--csv|--json] [--project <slug>]

Common invocations

~ — common report calls 
$ halton-meter report                           # last 30 days, all projects, both tables
$ halton-meter report --since 7d                # last 7 days
$ halton-meter report --from 2026-04-01 --to 2026-04-30
$ halton-meter report --project halton-meter
$ halton-meter report --by project             # only the by-project table
$ halton-meter report --by model               # only the by-model table
$ halton-meter report --vs-previous             # add Δ% vs the prior period of the same length
$ halton-meter report --csv                     # CSV to stdout
$ halton-meter report --json                    # JSON to stdout

--since accepts a bare integer (days) or a duration like 7d, 90d. --since is mutually exclusive with --from / --to.

A typical report

~ — halton-meter report 
$ halton-meter report --since 7d

halton-meter v0.1.24 · cost report · 2026-04-30 → 2026-05-07

✓ 3,142 requests across 5 projects · 7 models
✓ Tokens: 412,007 in · 2,180,453 out
✓ Total cost: $284.13

by project              requests        in        out          cost  avg latency  p95
────────────────────────────────────────────────────────────────────────────────────────
halton-meter                1,406   189,221   997,032    $132.77     11,204ms   28,113ms
billing                       712    81,503   411,889     $71.42      9,884ms   22,005ms
experiments                   401    52,118   289,114     $41.06     12,002ms   30,219ms

by model                requests        in        out          cost
────────────────────────────────────────────────────────────────────
claude-opus-4-7           1,888   223,011  1,567,002    $232.11
claude-sonnet-4-6           876   118,224   421,556     $36.78
claude-haiku-4-5            378    70,772   191,895      $5.24

Layout responsiveness

The report layout switches columns based on $COLUMNS (logic in daemon/halton_meter/report.py::_layout_for_width()):

WidthColumns shown
>= 110All seven + 7-day trend sparkline
90–109Drops the 7-day trend
70–89Drops p95 and trend
< 70Drops avg, p95, and trend

Column meanings

  • requests — count of metered request rows in the window
  • in / out — input / output token totals
  • cost — sum of cost_usd_minor_units / 100_000, formatted as USD
  • avg latency — mean wall-clock latency in milliseconds
  • p95 latency — 95th-percentile latency
  • 7d trend — rolling sparkline of daily request counts

Cost rows for which the model was unknown to the rate card show as — rather than $0.00. Run halton-meter recompute-costs after a rate-card update to backfill.

CSV and JSON export

--csv writes the report-style aggregation to stdout. For the per-request export (one row per captured call, with the column shape documented in SQLite schema), use the HTTP API:

curl -sS -OJ "http://127.0.0.1:8765/v1/projects/<slug>/requests.csv"

--json is the canonical machine-readable shape — preferred over CSV when feeding into another tool.

Other useful flags

FlagPurpose
--db <path>Read a different SQLite file. Useful for working on a copy without locking the live one.
--config <path>Override config.toml for this invocation.
--vs-previousAdd a Δ% column comparing to the prior window of the same length.

To pair this machine with a workspace, run the cloud connect command once with a scoped token.

What’s next