Installation

The installer accepts four optional environment variables:

Pass the variables to the shell that runs the installer:

$ curl -fsSL https://tokentriage.com/install.sh \
  | env TT_VERSION=v1.0.0 TT_INSTALL_DIR=/usr/local/bin sh

An internal mirror uses the same release layout under <base>/<repo>/releases/.... The installer still verifies the mirrored archive against that release’s checksums.

doctor checks the environment around the binary. It starts no service, writes no data, and prints no secrets:

$ tokentriage doctor
✓ binary — tokentriage dev (none), embedded pricing snapshot litellm@2026-07-14#179affb — clean
○ config — no config file (quickstart-less env) — checking the binary + defaults; pass --config to check one
    run: tokentriage doctor --config <path>   (to strictly check a specific config)
○ compile — skipped — no valid config to compile (see the config check)
✓ ports — listen 127.0.0.1:8787 bindable, admin 127.0.0.1:9090 bindable — clean
✓ ledger — C:\tt-home\.tokentriage\decisions.jsonl — 0 rows, 0 torn lines, writable — clean
✓ index — C:\tt-home\.tokentriage\index\decisions.sqlite — open, no rows indexed yet — clean
✓ pricing — embedded table litellm@2026-07-14#179affb loaded, no overrides configured — clean
○ keys — no config upstreams — no credential references to check
○ dashboard — skipped — no valid config (see the config check)
○ instance — not probed — pass --probe to check a running instance's admin plane over HTTP
    run: tokentriage doctor --probe                                   (probes the config's admin address)
    run: tokentriage doctor --probe --probe-url http://127.0.0.1:9090

ok — all checks passed (exit 0)

This capture came from a source build on Windows with no configuration file. A release prints its version instead of dev, paths follow your operating system, and configured checks replace the skipped ones. A failed check exits with status 1 in both text and --json output.

Use this path when Node 18+ or Python 3.9+ is already available, or when a CI job should not change the runner:

$ npx @tokentriage/cli run --anthropic
$ uvx tokentriage-cli run --anthropic

pipx run tokentriage-cli works like uvx.

The CLI is @tokentriage/cli on npm and tokentriage-cli on PyPI. The unscoped tokentriage package is the instrumentation SDK and does not contain an executable.

Both CLI packages carry the same prebuilt binary as the release archives. The npm package uses per-platform dependencies instead of downloading a binary in postinstall, so it also works with npm ci --ignore-scripts, registry proxies, and offline package caches.

Choose the package manager you already use:

$ brew install tokentriage/tap/tokentriage

Homebrew installs the same prebuilt binary as the one-line installer.

Container images use immutable version tags; no :latest tag is published. Use a named volume for the ledger so the non-root container can write to it:

$ docker run --rm \
  -p 8787:8787 -p 9090:9090 \
  -e ANTHROPIC_API_KEY \
  -v tokentriage-data:/data \
  ghcr.io/tokentriage/tokentriage:v1.0.0

Replace v1.0.0 with the release you want. The container configuration listens on 0.0.0.0 so Docker can publish its ports. The process runs as UID and GID 65532; if you use a host bind mount instead of the named volume, make that directory writable by this user first.

Install the Helm chart directly from the registry:

$ helm install tokentriage oci://ghcr.io/tokentriage/charts/tokentriage \
  --version 0.2.0

The chart version is independent of the TokenTriage release version. Run helm show chart oci://ghcr.io/tokentriage/charts/tokentriage to see both the chart version and appVersion.

Deployment and infrastructure covers the resources these commands create, along with Compose, Kustomize, Terraform, air-gapped operation, and supply-chain verification.

Open a new terminal first. A shell that was already running may still have the old PATH.

If that does not fix it, check where the binary landed and whether its directory is on PATH:

$ command -v tokentriage
$ printf '%s\n' "$PATH"

$ Get-Command tokentriage
$ $env:Path -split ';'

On macOS and Linux, add the install directory to your shell’s startup file, such as ~/.zshrc for zsh or ~/.bashrc for bash, then open another terminal. On Windows, add %LOCALAPPDATA%\Programs\tokentriage to your user PATH. The one-line installer prints the exact command when this is needed.

The installer stops before creating the install directory. Retry the download once in case it was interrupted. If you use TT_DOWNLOAD_BASE, confirm that the archive and checksums.txt came from the same mirrored release.

Choose a directory owned by your user and pass it with TT_INSTALL_DIR. The default directories are user-writable and do not require administrator rights.