CLI reference

tok0 exposes its functionality through a single binary with subcommands. All subcommands respect global flags like --config, --no-color, and --quiet.

Synopsis

tok0 [GLOBAL-FLAGS] <COMMAND> [ARGS]
tok0 <wrapped-cmd> [WRAPPED-ARGS]   # passthrough form

The first form runs a tok0 subcommand (tok0 init, tok0 stats, …). The second form is the proxy: any command tok0 knows about can be invoked as tok0 <cmd> and is compressed.

Global flags

Flag	Effect
--config <path>	Use an alternate config file (also via TOK0_CONFIG).
--quiet	Suppress non-error stderr (also TOK0_QUIET=1).
--no-color	Disable tok0’s own ANSI output (also NO_COLOR).
--log <level>	error, warn, info, debug, trace.
--version	Print version and build info.
--help	Show help.

Setup & maintenance

tok0 init

Detect every supported AI tool on this machine and install the right hook, rules file, or paste-in. Idempotent.

tok0 init
tok0 init --tools claude-code,cursor   # subset
tok0 init --remove                      # uninstall all hooks
tok0 init --dry-run                     # show what would happen

tok0 status

Per-tool bridge state: detected? wired? signature ok?

tok0 doctor

Full diagnostic: PATH wiring, config dir permissions, db reachability, hook signatures, AI tool detection, telemetry status. Run this whenever something feels off.

tok0 verify

SHA-256-check every installed hook against the embedded manifest. Exits non-zero on mismatch.

tok0 update

Self-update against GitHub Releases. Respects [updater].channel. No-op for package-manager installs.

Trust

tok0 trust [path]

Opt a project into loading its .tok0/filters/*.toml rules. Defaults to ..

tok0 untrust [path]

Revoke. Project-local rules become inert.

tok0 trust list

Print every trusted project path.

Insights

tok0 stats

Human dashboard: total tokens saved, top-N commands by savings, 30-day rolling chart drawn from your local SQLite meter.

tok0 stats               # default 30-day window
tok0 stats --days 7
tok0 stats --json        # machine-readable

tok0 costs

Translate token savings into $ at provider rates.

tok0 adoption

What fraction of agent commands hit a tok0 compressor.

tok0 profile

Per-compressor performance + size breakdown.

tok0 profile                    # all compressors
tok0 profile run "git diff"     # one-shot for a specific command

tok0 scan

Walk historical AI tool transcripts and report what tok0 would have saved if installed last month. Read-only — never modifies the transcripts.

Rules

tok0 rules list

Every rule loaded, with its source path (built-in / user / project).

tok0 rules show <name>

The resolved TOML, after overrides.

tok0 rules test <rule.toml> <fixture>

Apply the rule to a captured fixture. Prints raw size, compressed size, savings %, and assertion results.

Extensions

tok0 extensions install <git-url>

Clone a rule pack into ~/.config/tok0/extensions/<name> after a trust prompt.

tok0 extensions list

Installed extensions with their current commit hash.

tok0 extensions remove <name>

Delete the extension and unload its rules.

Telemetry

Off by default. All three forms work the same way and are identical to setting [telemetry].enabled directly.

tok0 telemetry on
tok0 telemetry off
tok0 telemetry status

Cloud (optional, gated)

Only present in builds with --features cloud. The default binary does not include these subcommands.

tok0 auth login [token]

Store a team API token in the OS keychain.

tok0 auth status

Whoami.

tok0 auth logout

Revoke.

tok0 cloud team

Open the team dashboard in a browser.

Proxy form

For every supported command, tok0 <cmd> runs the underlying tool, captures its output, runs the matching compressor, and prints the result. Exit code propagates exactly.

tok0 git diff
tok0 cargo build --release
tok0 npm install
tok0 kubectl get pods -A
tok0 docker build .

The full list of supported commands (~250) lives at Compressors.

Exit codes

Code	Meaning
0	Success.
1	Wrapped command exit code passed through.
2	Misuse: bad flags, missing args.
64	I/O error (config dir not writable, db locked).
65	Filter error AND raw fallback ALSO failed (rare; should never happen in production).
127	Wrapped command not found.

When wrapping a command, tok0 always propagates the wrapped command’s exit code if it ran. Tok0’s own errors only surface when the wrapped command never executed.