CLI Reference

Every subcommand, its flags, and a real sample output. All commands work offline with zero API key — the bundled corpus is self-contained.

distil bench

The corpus-wide CI gate. Iterates over all 7 trajectories, prices four strategies, runs the TOST non-inferiority gate on each, and confirms aggressive lossy compression is still rejected. Exits 0 only if every trajectory passes.

Flags

$ distil bench
corpus gate — 7 trajectories | model claude-opus-4-8 | tokenizer=heuristic

domain            trajectory               $ saved   distil   aggr  pruned
---------------------------------------------------------------------------
ops/sre           sre-disk-incident          33.1%     PASS   FAIL     615
coding            coding-bugfix              28.7%     PASS   FAIL     736
support           support-refund             32.6%     PASS   FAIL     765
research          research-synthesis         25.7%     PASS   FAIL     809
data-analysis     data-analysis-sql          18.1%     PASS   FAIL     965
devops            devops-rollback            25.0%     PASS   FAIL     857
finance           finance-reconcile          29.1%     PASS   FAIL    1014
---------------------------------------------------------------------------
aggregate: distil cuts $0.14212 -> $0.10402 (26.8% cheaper) losslessly; 5761 tokens prunable.

GATE: PASS — every trajectory certified non-inferior; aggressive rejected on all.

distil savings

Price four compression strategies on a single trajectory and show per-strategy cost, savings percentage, and cache hit tokens. The key result: naive compress + cache costs more than baseline because it busts the prefix cache.

Flags

$ distil savings --pricing claude-opus-4-8
model claude-opus-4-8   |   4 turns   |   tokenizer=heuristic (≈, not billing-grade)

strategy                               $ / run   vs baseline  cache hits
------------------------------------------------------------------------
baseline (no cache, no compress)       0.01524          0.0%           0
cache only                             0.01115         26.8%       1,028
naive compress + cache                 0.01691        -11.0%           0
distil (cache-aware lossless)          0.01019         33.1%       1,028
------------------------------------------------------------------------
distil cuts $0.01524 -> $0.01019 per run (33.1% cheaper), losslessly.
note: naive compression costs $0.01691 — 66% MORE than distil despite fewer tokens,
      because it busts the prefix cache.

distil certify

Run the TOST non-inferiority gate on a single trajectory and strategy. Exits 0 on PASS, 1 on FAIL. Use this as the unit-level quality check; use bench for the corpus-wide gate.

Flags

$ distil certify --strategy distil
certifying strategy 'distil' on 'sre-disk-incident' (runner=deterministic)

  turn 0: ok
  turn 1: ok
  turn 2: ok
  turn 3: ok

decision-equivalence match rate: 100.0%
TOST non-inferiority (margin=0.02, alpha=0.05): mean diff=+0.000, p=0.0000

VERDICT: PASS  (certified non-inferior)

$ distil certify --strategy aggressive
certifying strategy 'aggressive' on 'sre-disk-incident' (runner=deterministic)

  turn 0: DIVERGED
      baseline:   use_tool(bash, {"cmd":"df -h /"})
      compressed: use_tool(bash, {"cmd":"ls /"})
  turn 1: DIVERGED
  turn 2: DIVERGED
  turn 3: DIVERGED

decision-equivalence match rate: 0.0%
TOST non-inferiority (margin=0.02, alpha=0.05): mean diff=-1.000, p=1.0000

VERDICT: FAIL  (NOT certified — would degrade quality)

distil prune

Causal ablation: for each context block, remove it and replay the trajectory. Blocks that never change a decision are causally inert — provably free to drop.

Flags

$ distil prune
causal ablation over 'sre-disk-incident' — what is free to drop?

block                  occ   tokens  verdict
doc-0                    4      312  PRUNE (causally inert)
doc-1                    4      303  PRUNE (causally inert)
obs-0                    4      234  keep (changed a decision)
obs-1                    4      198  keep (changed a decision)
system                   4      218  keep (changed a decision)

tokens provably free to drop: 615 across 2 block(s).

distil compress

Apply the distil strategy to a trajectory turn by turn and report the per-turn token reduction and overall reversibility status.

Flags

$ distil compress
trajectory 'sre-disk-incident'  (4 turns, tokenizer=heuristic)

turn    before     after   saved
   0      1824      1312   28.1%
   1      1956      1401   28.4%
   2      2108      1518   28.0%
   3      2340      1689   27.8%

 ALL      8228      5920   28.1%

reversible: yes (Tier-0/1) — 3 blocks digested, originals recoverable locally

distil verify

Byte-fidelity gate: confirms every Tier-0/1 compression across the corpus is byte-reversible, and that frozen history never mutates between turns (append-only invariant). Exits 0 only if all checks pass.

No flags. Runs across the full bundled corpus.

$ distil verify
byte-fidelity gate — reversibility + append-only across the corpus

  sre-disk-incident        reversible + append-only: ok
  coding-bugfix            reversible + append-only: ok
  support-refund           reversible + append-only: ok
  research-synthesis       reversible + append-only: ok
  data-analysis-sql        reversible + append-only: ok
  devops-rollback          reversible + append-only: ok
  finance-reconcile        reversible + append-only: ok

FIDELITY: PASS — Tier-0/1 byte-reversible and history append-only across the corpus.

distil holdout

Holdout A/B savings measurement. Partitions the corpus into a control group (held out, not counted toward the headline) and a treatment group, reports savings with a bootstrap 95% confidence interval.

Flags

$ distil holdout
holdout A/B savings measurement (deterministic partition + bootstrap CI)

  treatment savings: 27.4% [95% CI: 24.1%–30.8%]
  control group mean savings: 26.1% (held out, not counted toward the headline)

distil leaderboard

Shows cumulative savings from all runs recorded via --record flags on savings and bench. Local-first; no data leaves the machine unless you opt in to community sharing (not currently enabled).

No flags.

$ distil leaderboard
distil savings ledger — ~/.local/share/distil/ledger.jsonl

runs recorded:        12
total tokens saved:   42,816
total dollars saved:  $0.51234

by trajectory:
  corpus-aggregate             $0.38112
  sre-disk-incident            $0.13122

(local-first; community sharing is opt-in and not enabled.)

distil proxy (in progress)

HTTP proxy that applies Distil compression to every LLM API request passing through it. Drop-in for any client that honours a base_url parameter — Anthropic SDK, OpenAI SDK, LiteLLM, LangChain, etc.

The proxy is currently available as a Python module (python -m distil.proxy). A CLI subcommand wrapping the same server is being added.

Flags (module / upcoming CLI)

$ python -m distil.proxy --port 8788 --upstream https://api.anthropic.com
distil proxy listening on http://127.0.0.1:8788
  → upstream: https://api.anthropic.com

Point your SDK at the proxy:

# Anthropic SDK
client = anthropic.Anthropic(base_url="http://localhost:8788")

# OpenAI-compatible client
client = openai.OpenAI(base_url="http://localhost:8788/v1")

# LiteLLM
response = litellm.completion(api_base="http://localhost:8788", ...)

The proxy adds two response headers: x-distil-compressed: 1 and x-distil-tokens-saved: <n>. All other paths and HTTP methods are forwarded unchanged.

See Adapters for the full story on in-process vs. proxy adoption.

Full CI gate

$ make gate
# Runs: tests + corpus non-inferiority (distil bench) + byte-fidelity (distil verify)

pytest ... 181 passed in 4.2s
corpus gate: PASS
fidelity gate: PASS