Run kache <command> --help for the exact syntax in your installed version.

--json emits one versioned JSON document for list, stats, gc, clean, doctor, why-miss, and daemon status. clean --json is a preview unless --yes is also present.

kache cargo

kache cargo -- build
kache cargo -- test --workspace

Pass Cargo arguments after --. On Cargo 1.91 or newer, this command can keep intermediate worktree state separate while coordinating a shared final target directory.

kache list

kache list
kache list serde
kache list --sort size --no-pager

Sort values are name, size, hits, and age.

Interactive output uses KACHE_PAGER, then PAGER, then a platform default. --no-pager writes directly.

kache gc

kache gc
kache gc --max-age 7d
kache gc --stale-schema

A bare run enforces configured size and age policies. --max-age runs the requested age policy. --stale-schema removes entries created with old or unrecorded key schemas and conflicts with --max-age.

GC affects only the local store.

GC reports store bytes removed separately from bytes reclaimed on disk. It keeps an entry when its last store blob is still cloned into a build output, because unlinking that blob would free no disk and destroy a usable hit. This can leave the registered store size above cache.local_max_size; remove stale targets to reclaim the blocks.

Set cache.gc_evict_shared = true or KACHE_GC_EVICT_SHARED=1 to restore the older namespace-first policy. That lowers the registered store size but does not reclaim blocks retained by target directories, and the discarded entry becomes a future miss. See Configuration: GC and shared build outputs.

kache purge

kache purge --crate-name serde
kache purge

With no crate name, purge wipes the entire local cache after confirmation.

kache clean

kache clean
kache clean --dry-run
kache clean --yes
kache clean --tracked --stale 14d --dry-run
kache clean --tracked --stale 14d --yes

clean recursively finds target/ directories below the current directory. The default opens a selector. Use --dry-run before a scripted --yes run.

--tracked uses the bounded machine-local target registry populated by normal builds and restores. --stale filters by last use. Cleanup rechecks each directory identity and removes only the derived target directory; missing, moved, replaced, current-workspace, and unsafe paths are skipped.

kache init

kache init
kache init --check
kache init --no-service
kache init --yes

--check reports proposed changes without writing. --no-service skips login-service installation. Besides rustc-wrapper, init adds HOST_CC / HOST_CXX / CC_KNOWN_WRAPPER_CUSTOM under Cargo [env] when those keys are absent. It never sets CC or CXX.

kache doctor

kache doctor
kache doctor --fix
kache doctor --verify
kache doctor --checksums
kache doctor --repair

• --fix repairs supported setup issues and can migrate sccache configuration.
• --purge-sccache also removes sccache data and requires --fix.
• --verify checks entries, blobs, and metadata.
• --checksums also hashes blob contents and implies --verify.
• --repair removes corrupted entries and implies --verify.

Review destructive options before running them.

kache sync

kache sync
kache sync --pull
kache sync --push
kache sync --dry-run
kache sync --pull --workspace
kache sync --pull --all

Options:

See Sync for filtering semantics.

kache save-manifest

kache save-manifest
kache save-manifest --manifest-key x86_64-linux-release
kache save-manifest --namespace x86_64-unknown-linux-gnu/rustc-hash/release

Without --manifest-key, Kache publishes an identity key (id/<lock-digest>/<target>/<profile> when Cargo.lock and a profile are known) and the host target triple so older prefetch still finds the file. KACHE_MANIFEST_KEY or --manifest-key writes a single key. A namespace plus Cargo.lock also publishes content-addressed shards.

kache daemon

kache daemon             # status
kache daemon status
kache daemon run
kache daemon start
kache daemon stop
kache daemon restart
kache daemon install
kache daemon uninstall
kache daemon log

See Daemon lifecycle.

kache monitor

kache monitor
kache monitor --since 7d

--since takes the same forms as kache stats.

See Monitor.

kache stats

kache stats
kache stats --since 15m
kache stats --since 2h
kache stats --last-build --root "$PWD"

--since accepts s, m, h, and d units (90s, 15m, 2h, 7d). A bare number is hours. The default is 24h. The counters and the last ... label both describe the requested window; a value that does not parse is an error.

--last-build shows the detailed report for the latest recorded activity session. Add --root to choose a build tree; without it, the latest event across all roots chooses the session. It cannot be combined with --since. With --json, the stats envelope contains a report object using the build report schema below.

kache telemetry

kache telemetry write ./cache-otlp
kache telemetry write ./cache-otlp --scenario bench-firefox --phase warm

Writes metrics.otlp.json and schema_version for Kartero. Metric names are kache.cache.* / kache.prefetch.* (scope kache.cache), never kache.bench.*. --scenario must match kache.bench.project. --phase is cold, warm, or pull so dumps from the same scenario do not collide. The rustc wrapper does not write these files.

kache why-miss

kache why-miss serde

The command compares recorded key material for the named rustc crate and reports changed input groups.

kache report

kache report --format text --since 24h
kache report --format markdown --root "$PWD"
kache report --last-build --root "$PWD" --format markdown
kache report --format json --output report.json
kache report --format trace --output trace.json

trace, perfetto, and chrome-trace select the same trace representation. The JSON contract is documented by report.schema.json.

--last-build selects by the latest compiler event timestamp across the retained log, including events older than 24 hours. It includes only that root and session ID. For local or older events without session IDs, it infers a session from overlapping compiler activity and gaps shorter than five minutes, stopping at an event with a recorded ID. The report states which rule it used. --root limits the search to that tree and its descendants; the selected session still belongs to one exact root.

A session can span concurrent or nearby Cargo commands. This flag does not identify one Cargo invocation. Cargo commands that do no compiler work produce no new events, running compiles have not been logged yet, and log rotation can remove the start of a session. An empty selection is an error.

The session report includes cache hits, misses, bypass reasons, restored bytes and the observed compiler wall span. Compile work avoided is an aggregate estimate, not elapsed build time saved. Remote transfer totals and GC are omitted because those logs cannot identify the selected session. Store inventory and deduplication totals still describe the whole cache.

JSON exposes the selection in meta.session (root, optional session_id, inferred, inactivity_secs); trace output carries it as session. In session reports, since_secs and since_hours describe the lookback to the first retained compiler start; meta.session defines the selection.

Every report format totals the wrapper's phases per crate: startup (process start to wrapper entry), key computation with the rustc dep-info pre-pass split out by time and run count, lookup, scheduler wait (flight join plus permit acquisition), restore or store, and the unattributed remainder. Unattributed is wrapper overhead minus every measured phase, where overhead excludes the compile on a compiled crate and is the whole wrapper time on a hit. Events written by wrappers before schema 17 report zero startup, dep-info and wait time.

In the trace output each crate slice carries these numbers in its args and nests one X slice per phase on the same lane, in the order startup, key (with dep-info as its child), lookup, wait, compile on compiled crates, then restore or store. Phase offsets accumulate from the crate slice's start in that order; the wrapper records durations, not start times, so a phase sits where it lands in the sum. The gap after the last phase is the unattributed remainder. Durations are whole milliseconds, so a phase under 1 ms has no slice.

kache config

kache config

This command can open even when the current config file is invalid. See Configuration.

kache install-shims

kache install-shims
kache install-shims --from-path
kache install-shims --force ~/.local/lib/kache/shims

Unix only. Creates cc, c++, gcc, g++, clang, and clang++ symlinks to Kache. With no directory argument the farm is ~/.local/lib/kache/shims. --from-path also wraps compiler names already on PATH (gcc-13, target-prefixed drivers). Put the directory before the real compilers in PATH. See C and C++.

kache completions

kache completions zsh > ~/.zfunc/_kache
kache completions bash > ~/.local/share/bash-completion/completions/kache
kache completions fish > ~/.config/fish/completions/kache.fish

Supported shells are Bash, Elvish, Fish, PowerShell, and Zsh.