Core commands

Most TokenShift activity happens transparently — the agent’s tool calls flow through the hook, and there’s nothing to type. These are the commands a developer or admin might run by hand.

tokenshift doctor

The single command you run to answer “is it set up correctly?”

tokenshift doctor             # status check, no network
tokenshift doctor --verify    # also ships one synthetic record to confirm the wire is live end-to-end

Reports, in one block: which agent hooks are wired, whether an enrollment manifest is present (and which one — per-user shadows system), what tier and config are active, and the result of the binary’s internal self-check.

Run this after tokenshift install, after pushing a new manifest via MDM, and any time something feels off. tokenshift doctor --verify is the canonical “did MDM rollout actually work?” check.

tokenshift dashboard

Interactive terminal UI that shows compression savings over time — tokens saved, cost saved, per-rule rollups, per-project / per-model / per-activity slices. Reads from local stats only; no network calls.

tokenshift dashboard

Useful as a quick gut-check on whether TokenShift is actually saving tokens on a developer’s machine, and which rules are pulling the most weight.

tokenshift enroll

Installs a tenant-bound enrollment manifest from the PointFive app. The full enrollment model — what’s in the manifest, where it lives on disk, per-user vs. system delivery — is in Enrollment.

tokenshift enroll ~/Downloads/enrollment.json   # the common case
tokenshift enroll -                              # read from stdin
tokenshift enroll --dry-run <path>               # validate without writing

Validates the JSON before writing. Writes with 0600 to a 0700-mode parent. Never overwrites silently — use --force for deliberate replacement.

tokenshift backfill

Reconstructs token usage and tool activity from each harness’s own historical session transcripts already on disk, and ships it — so a fresh install doesn’t start the dashboard from zero.

tokenshift backfill                         # ship everything new since the last run
tokenshift backfill --dry-run               # preview without shipping or advancing state
tokenshift backfill --agent claude-code     # limit to one harness
tokenshift backfill --all                   # ignore the per-session ledger, re-ship everything

Runs automatically, once, right after a successful tokenshift enroll — it’s rarely something you need to run by hand. Reach for it manually to retry after a failed automatic attempt, preview what would ship with --dry-run, or replay one session with --session <id> while debugging.

Only harnesses with a durable on-disk session store support this today — Claude Code and GitHub Copilot CLI. Cursor and Codex don’t have a backfillable local store yet; running it against either just reports “no backfill source yet” and skips.

Same privacy guarantees as the live hooks: every reconstructed event is redacted at the same tier as anything shipped in real time (including the local intent classifier, if it’s warm — see How it works), and nothing ships unless telemetry is enabled (--dry-run previews regardless). Re-runs are idempotent — a per-session ledger tracks what’s already shipped, so nothing is double-counted.

tokenshift recover <hash>

Pulls back the full uncompressed output of a tool call that TokenShift previously compressed. The agent uses this automatically (the compressed response ends with tokenshift recover <hash> and the model learns to ask for it when it needs more detail), but a developer can run it too.

tokenshift recover a1b2c3d4

Reads from the local recovery cache only. The cache is local-only with a 1-hour TTL — past that, the original is no longer available.

Only works on harnesses where the compressing proxy runs unsandboxed: Claude Code and GitHub Copilot CLI. Cursor and Codex sandbox the proxy, so it can’t write the cache — compression and telemetry still work for both, there’s just nothing for recover to replay. See Recovery cache scope.

tokenshift config telemetry

Toggle or inspect what leaves the laptop. Subject to the install-time cap set by the customer admin’s manifest.

tokenshift config telemetry enable         # opt in (within the admin-permitted tier)
tokenshift config telemetry disable        # opt out — local stats only
tokenshift config telemetry mode <name>    # metrics | patterns | samples

The three named modes are the actual user-facing surface over the wire tiers — each strictly adds to the one before it:

Mode	Wire tier	Adds
metrics	1	Operational stats only — rule, tokens, timings, command hash. The server sees that a command ran, never what it was.
patterns	2	+ redacted command patterns (e.g. kubectl get pods <NAMESPACE>) — flag names kept, values stripped, capped and fail-closed.
samples	4	+ redacted input/output samples, but only for the specific rules the admin allowlisted — used to tune compression strategies.

The tenant’s manifest caps the ceiling — asking for a richer mode than the admin permits silently degrades to the cap rather than erroring, so if a mode change doesn’t seem to show up server-side, check the effective tier with tokenshift doctor before assuming something’s broken. See Tiers in the data contract for exactly what each wire tier carries.

tokenshift config on its own prints the effective config (defaults merged with ~/.tokenshift/config.toml); tokenshift config path prints where that file lives.

tokenshift update

Self-update to the latest release on the stable channel. Resolves the version via the /v1/version/latest endpoint, verifies the signed artifact, and atomically swaps the binary.

tokenshift update              # update in place; verbose by default
tokenshift update --check      # show what would happen, no swap
tokenshift update --print-url  # emit the presigned URL (for `curl -L` pipelines)

For MDM-managed fleets, don’t wire this into a cron — the admin’s MDM is the upgrade authority. tokenshift update is for developer machines where the binary was installed manually from the PointFive installation page.

tokenshift version

tokenshift version

Prints the running binary version, build date, and whether the binary is pinned (configured to ship telemetry) or unpinned (telemetry will not ship).

tokenshift uninstall

Removes the hooks from the agent’s settings. Does not by default touch the local cache or the enrollment manifest.

tokenshift uninstall          # remove hooks only
tokenshift uninstall --purge  # also remove ~/.tokenshift/ (cache, stats, client_id)

The system-deployed enrollment manifest at /etc/tokenshift/ (Linux/macOS) or %PROGRAMDATA%\tokenshift\ (Windows) is left alone — that’s the MDM’s responsibility to remove.

Note

There is also tokenshift proxy <command> for invoking TokenShift explicitly on a single command, and tokenshift install for first-time hook wiring (covered in Quickstart). Other subcommands exist but are operational/internal — these ten cover everything a developer or admin would touch in normal use.