Command reference
When invoked without arguments, kache prints --help and exits — it does not open the TUI monitor (launch it explicitly with kache monitor). When invoked with a subcommand, it runs that command. When invoked as RUSTC_WRAPPER (detected by the rustc path in argv[1]), it operates as a transparent build cache.
Quick reference
| Command | Description |
|---|---|
kache | Print --help and exit (use kache monitor for the live TUI) |
kache init [-y] [--no-service] [--check] | Interactive setup: cargo wrapper + service install + daemon start |
kache monitor [--since <dur>] | Open the live TUI dashboard, optionally scoped to a time window |
kache stats [--since <dur>] | One-shot stats snapshot, no interactive UI |
kache list [<crate>] [--sort <field>] | List cache entries or show details for one crate |
kache why-miss <crate> | Diagnose why a crate keeps missing the cache |
kache report [--format <fmt>] [--since <dur>] [--root <path>] [--output <path>] [--top <n>] | Build report in text / json / trace / markdown / github format |
kache gc [--max-age <dur>] | Evict entries by LRU or age |
kache purge [--crate-name <name>] | Wipe entire cache or entries for one crate |
kache clean [-n | --dry-run] [-y | --yes] | Find and remove target/ directories (interactive; -n previews, -y removes all non-interactively) |
kache sync [flags] | Sync local cache with S3 remote |
kache save-manifest [--manifest-key <key>] [--namespace <ns>] | Save a build manifest for future prefetch warming |
kache doctor [--fix [--purge-sccache]] [--verify] [--checksums] [--repair] | Diagnose and fix setup issues; verify cache integrity |
kache config | Open the TUI configuration editor |
kache completions <shell> | Print shell completion script (bash, zsh, fish, elvish, powershell) |
kache daemon [subcommand] | Manage the background daemon |
Duration arguments accept days or hours: 7d, 24h, or a bare number of hours like 48. Minutes are not supported — a value like 30m fails to parse and silently falls back to the default.
kache init
kache init [-y] [--no-service] [--check]Interactive setup. Edits ~/.cargo/config.toml (or the legacy extensionless ~/.cargo/config if that file already exists) to set rustc-wrapper = "kache", installs the daemon as a login service (launchd on macOS, systemd user unit on Linux, Task Scheduler on Windows), and starts it. Idempotent — safe to re-run any time to repair configuration.
kache init # interactive prompts
kache init -y # accept all defaults non-interactively
kache init --no-service # configure cargo wrapper but skip the system service install
kache init --check # report what init would do, change nothingIf you'd rather wire things up manually, see Quick start.
kache monitor
kache monitor [--since <duration>]Opens the live TUI dashboard. --since controls how far back the build event log is read when the monitor starts. Defaults to showing all available events. The Passthrough tab lists uncached invocations with their reason and fallback/direct route.
kache monitor --since 24hSee Monitor for a full description of the tabs and fields.
kache stats
kache stats [--since <duration>]Prints a one-shot cache statistics summary to stdout without opening the interactive UI. Useful for CI log output or scripting.
kache stats --since 7dkache list
kache list [<crate-name>] [--sort name|size|hits|age]Without a crate name, lists all cached entries with sort control. With a crate name, shows all cached entries for that specific crate including cache keys, artifact sizes, features, and targets.
kache list # all entries, sorted by name
kache list --sort size # largest first
kache list --sort hits # most frequently used first
kache list serde # all entries for serdekache report
kache report [--format text|json|trace|perfetto|chrome-trace|markdown|github] [--since <duration>] [--root <path>] [--output <path>] [--top <n>]Generates a detailed report of recent build activity: per-crate hit/dup/miss counts, cumulative time saved, transfer activity, and store stats. Useful for sharing CI results in a PR comment or feeding the data into other tools.
Reports keep cache outcomes separate:
hitmeans kache restored the artifact without running the compiler.dupmeans the cache key missed, the compiler ran, and the compiled bytes already existed in the local store.missmeans the cache key missed, the compiler ran, and at least one output blob was new.
Hit rate counts hits only. Compiled work is reported as dups + misses.
--top <n> limits how many crates appear in the per-crate breakdown (default 10).
kache report # text to stdout
kache report --format markdown --since 24h # markdown summary, last 24 hours
kache report --format github --output report.md # GitHub-flavored, written to a file
kache report --format json | jq # machine-readable summary
kache report --format perfetto --output trace.json # Chrome trace / Perfetto import
KACHE_EVENT_ROOT="$PWD" cargo build
kache report --format perfetto --root "$PWD" --since 24h --output trace.jsonFor timeline analysis, JSON reports include a timeline window plus a top-level traceEvents array and displayTimeUnit: "ms" hint. --format trace, --format perfetto, and --format chrome-trace emit only those trace-viewer fields for Chrome trace / Perfetto import. Each trace event is a complete event (ph: "X") with microsecond ts / dur fields and kache result details in args. Per-invocation entries in all_events, top_hits, and top_misses also include root, start_time, end_time, start_unix_ms, and end_unix_ms alongside the result, cache key, elapsed time, compile time, overhead, artifact size, and compiler/preprocessor/probe counts. Use --root <path> to isolate a benchmark checkout/build tree when the event log contains other compilations. kache derives root automatically where possible; benchmark harnesses can set KACHE_EVENT_ROOT to stamp all wrapper events with an explicit root. External build-system traces can be merged into the same Perfetto view when they share, or are normalized to, the same timebase, but kache's own hit/miss timeline does not depend on another tracing tool.
The github format is friendly for posting as a PR comment via gh pr comment --body-file.
kache save-manifest
kache save-manifest [--manifest-key <key>] [--namespace <ns>]Records the resolved set of crates / cache keys for the current workspace as a build manifest. The remote planner (see Remote service) consumes manifests to warm prefetch hints for future runs that look like the same workspace.
--manifest-key <key>overrides the manifest key (defaults to the host target triple).--namespace <ns>enables content-addressed shard uploads (requires aCargo.lock); it can also be supplied via theKACHE_NAMESPACEenvironment variable, with the flag taking precedence. With no namespace, only the monolithic manifest is uploaded and shard upload is skipped.
kache save-manifest # upload the monolithic manifest only
kache save-manifest --namespace ci-main # also upload shards, tagged by environmentSaving a manifest is cheap; it is safe to run at the end of a CI build alongside kache sync --push.
kache gc
kache gc [--max-age <duration>]Runs garbage collection. Without --max-age, evicts the least-recently-used entries until the store is under KACHE_MAX_SIZE. With --max-age, removes all entries older than the specified duration regardless of store size.
kache gc # LRU eviction to stay under max size
kache gc --max-age 30d # remove anything unused for 30 days
kache gc --max-age 7d # aggressive cleanup before a release buildIf clean_incremental is enabled (the default), GC removes tracked incremental compilation directories that previous wrapper invocations registered. Active wrapper invocations also remove the current build's incremental dir eagerly.
kache purge
kache purge [--crate-name <name>]Removes cache entries permanently. Without --crate-name, wipes the entire local cache. With --crate-name, removes only entries for that crate. This does not affect the remote cache.
kache purge # wipe everything
kache purge --crate-name tokio # remove all tokio entrieskache purge without a crate name removes your entire local cache. The next build will be a full cold build.
kache clean
kache clean [-n | --dry-run] [-y | --yes]Recursively finds all target/ directories under the current directory and removes them. Reports disk usage per directory before deleting, including how much of each target/ is already cached in kache's store — so you can see at a glance which projects are safe to wipe.
With no flags, clean opens an interactive selector (shown below). For scripts and cron, pass -y/--yes to skip the selector and remove every target/ directory found, or -n/--dry-run to preview what would be removed without deleting. If both are given, --dry-run wins.
Static layout for reference:
┌ kache clean ──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 8 dirs (73.2 GiB total, 7.4 GiB cached) Selected: 0 (0 B) │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌ Select directories to remove ─────────────────────────────────────────────────────────────────────────────────────┐
│ [ ] workspace/compiler-core/target 34.7 GiB 5.7 GiB [debug, release]│
│ [ ] workspace/build-cache/target 15.4 GiB 49.1 MiB [debug, release]│
│ [ ] workspace/desktop-app/crates/app/target 13.8 GiB 9.4 MiB [debug] │
│ [ ] workspace/service-api/target 3.0 GiB 239.2 MiB [debug] │
│ [ ] workspace/frontend/packages/graph-core/target 2.2 GiB 635.6 MiB [debug] │
│ [ ] workspace/auth-service/target 1.5 GiB 727.4 MiB [debug] │
│ [ ] workspace/metrics/target 1.5 GiB 0 B [debug] │
│ [ ] workspace/frontend/packages/ipc-plugin/target 1.1 GiB 152.8 MiB [debug] │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌ workspace/compiler-core/target — 34.7 GiB total, 5.7 GiB cached (16%) ────────────────────────────────────────────┐
│ incremental: 0 B build: 433.3 MiB deps (local): 28.4 GiB │
│ fingerprint: 5.9 MiB binaries: 239.5 MiB other: 6.9 KiB │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ space: toggle a: select all n: select none enter: delete selected q: cancel │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘kache clean # interactive selector
kache clean -n # preview what would be deleted (alias: --dry-run)
kache clean -y # non-interactive: delete all target/ dirs (alias: --yes)This is useful for freeing disk space when you're done with a project or before a fresh build.
On macOS, the scan skips TCC-protected locations (/System, /Library, /private, /Applications, /Volumes, and home folders like ~/Desktop, ~/Documents, ~/Downloads, ~/Library, ~/Pictures) to avoid permission prompts, so target/ directories under those paths are never found or cleaned.
kache sync
kache sync [--pull] [--push] [--all] [--dry-run] [--manifest-path <path>]Synchronizes the local cache with the configured S3 remote. See Sync for a full walkthrough.
kache sync # pull missing + push new artifacts
kache sync --pull # download only, filtered to current workspace
kache sync --pull --all # download everything in the bucket
kache sync --push # upload only
kache sync --dry-run # preview transfers, make no changeskache why-miss
kache why-miss <crate-name>Compares the cache key from the most recent recorded entry for the given crate against the current build inputs, and reports which component of the key changed. Useful for diagnosing persistent cache misses.
kache why-miss tokiokache doctor
kache doctor [--fix [--purge-sccache]] [--verify] [--checksums] [--repair]Diagnoses common setup issues: missing RUSTC_WRAPPER, conflicting wrappers, config file problems, and daemon connectivity. Without --fix, it only reports issues.
The verify family checks cache integrity:
--verifychecks entry, blob, and metadata integrity (orphaned/missing blobs).--checksumsadditionally re-hashes blob contents to catch silent corruption (slower; implies--verify).--repairremoves corrupted entries and sweeps orphaned blobs (implies--verify).
kache doctor # diagnose only
kache doctor --fix # attempt to fix detected issues
kache doctor --verify # check cache integrity
kache doctor --repair # remove corrupted entriesIf you're migrating from sccache, --fix handles the migration automatically. --purge-sccache additionally removes sccache's cache and binary:
kache doctor --fix --purge-sccachekache config
kache configOpens the TUI configuration editor. Shows all config fields, their current values, and which ones are overridden by environment variables. Saves changes to the active config file: $KACHE_CONFIG if set, else the nearest .kache.toml in a parent directory, else the global ~/.config/kache/config.toml ($XDG_CONFIG_HOME/kache/config.toml).
kache completions
kache completions <shell>Prints a completion script for the given shell to stdout. Supported shells: bash, zsh, fish, elvish, powershell. Does not require a valid kache config.
Install examples:
# zsh — write to a directory on fpath, then restart the shell
mkdir -p ~/.zfunc
kache completions zsh > ~/.zfunc/_kache
# ensure fpath+=(~/.zfunc) before compinit, then: exec zsh
# bash
kache completions bash > ~/.local/share/bash-completion/completions/kache
# fish
kache completions fish > ~/.config/fish/completions/kache.fishAlternatively, load completions for the current session:
eval "$(kache completions bash)" # bash
eval "$(kache completions zsh)" # zsh (compinit must already be active)
kache completions fish | source # fishkache daemon
kache daemon # show daemon status: service install state, running/offline, socket path, log location, daemon version/epoch
kache daemon status # same as above (explicit alias)
kache daemon start # start in background, wait until ready
kache daemon stop # graceful shutdown
kache daemon restart # restart (via launchd/systemd/Task Scheduler if installed, else manual)
kache daemon run # start in foreground (for debugging)
kache daemon install # install as a system service (launchd/systemd/Task Scheduler)
kache daemon uninstall # remove the system service
kache daemon log # stream the daemon logSee Daemon lifecycle for details on service installation and the auto-restart behavior.