COMMAND-LINE REFERENCE

One command, local reports

Use ./run from a source checkout, or tokens after a local editable install.

Syntax

tokens [day|week|month|all|dashboard|serve|doctor] [options]

Commands and ranges

Command	Default window	Result
`day`	Last 14 days	Daily terminal report; the default command.
`week`	Last 8 weeks	Weekly terminal report.
`month`	Last 6 months	Monthly terminal report.
`all`	All available history	Daily terminal report.
`dashboard`	Selected history	Self-contained offline HTML snapshot with day/week/month views.
`serve`	Selected history	Loopback-only live dashboard; checks local logs every five minutes by default.
`doctor`	Not applicable	Safe environment and source diagnostics.

Options

Option	Meaning
`--source SOURCE`	Select `claude`, `gemini`, or `codex`; repeat to combine.
`--since YYYY-MM-DD`	Inclusive start date.
`--until YYYY-MM-DD`	Inclusive end date.
`--days N`	Positive day-mode window; default 14.
`--weeks N`	Positive week-mode window; default 8.
`--months N`	Positive month-mode window; default 6.
`--timezone AREA/CITY`	IANA timezone override; system local timezone is detected by default.
`--output DIR`	Report directory; default `./out`.
`--html`	Add a static HTML report to a terminal range.
`--dashboard`	Generate the dashboard regardless of the positional range.
`--anonymize`	Pseudonymize project, session, and natural-language title identifiers; dashboard or serve only.
`--interval SECONDS`	Initial live check interval; minimum 1, default 300. The page can select 1, 5, 15, or 30 minutes, or pause.
`--port PORT`	Live loopback port; default 8765, or 0 to choose an available port.
`--open`	Open generated HTML or the live local URL in the default browser.
`--no-cache`	Ignore the user file cache and parse selected logs again.
`--version`	Print the installed version.

Examples

tokens doctor

tokens week --source claude --source gemini

tokens month --months 12 --timezone America/New_York

tokens serve --open

tokens serve --port 0 --interval 2 \
  --source claude --source gemini

tokens dashboard --output ~/Reports/tokens --open

tokens dashboard --anonymize \
  --since 2026-08-01 \
  --until 2026-08-31

Behavior and paths

The default source is Claude; Gemini and Codex are opt-in.
Reports default to ./out, not the installed package directory.
The parsed-file cache lives in the platform user cache directory, separate from reports.
Dates are interpreted in the detected system timezone unless --timezone is supplied.
An invalid date, timezone, range, or non-positive window exits with status 2.
No records exits with status 1 and points to tokens doctor.
The live server binds only to 127.0.0.1, accepts no LAN bind option, and can stay open while waiting for future records.
Live checks first compare safe file modification-time and size signatures; unchanged files are not re-parsed or re-sent.
--no-cache disables parsed-file reuse when a live change is detected; it does not turn unchanged polling into repeated full parsing.
A browser-open failure does not stop the live server or delete a generated report.
--anonymize is pseudonymization, not guaranteed anonymity.