Command reference
When invoked without arguments, kache opens the TUI 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 | Open the live TUI monitor |
kache init [-y] [--no-service] [--check] | Interactive setup: cargo wrapper + service install + daemon start |
kache monitor [--since <dur>] | Same as bare kache, with optional 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>] [--output <path>] | Build report in text / json / 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 [--dry-run] | Find and remove target/ directories |
kache sync [flags] | Sync local cache with S3 remote |
kache save-manifest [--namespace <ns>] | Save a build manifest for future prefetch warming |
kache doctor [--fix [--purge-sccache]] [--verify] | Diagnose and fix setup issues; verify cache integrity |
kache config | Open the TUI configuration editor |
kache daemon [subcommand] | Manage the background daemon |
Duration arguments use a human-friendly format: 7d, 24h, 30m.
kache init
kache init [-y] [--no-service] [--check]Interactive setup. Edits ~/.cargo/config.toml to set rustc-wrapper = "kache", installs the daemon as a login service (launchd on macOS, systemd user unit on Linux), 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|markdown|github] [--since <duration>] [--output <path>]Generates a detailed report of recent build activity: per-crate hit/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.
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 summaryThe github format is friendly for posting as a PR comment via gh pr comment --body-file.
kache save-manifest
kache save-manifest [--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.
kache save-manifest # default namespace (workspace name)
kache save-manifest --namespace ci-main # tag manifests 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 [--dry-run]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.
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 --dry-run # preview what would be deleted
kache clean # delete all target/ directoriesThis is useful for freeing disk space when you're done with a project or before a fresh build.
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]]Diagnoses common setup issues: missing RUSTC_WRAPPER, conflicting wrappers, config file problems, and daemon connectivity. Without --fix, it only reports issues.
kache doctor # diagnose only
kache doctor --fix # attempt to fix detected issuesIf 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 directly to ~/.config/kache/config.toml.
kache daemon
kache daemon # show daemon status (running, PID, version)
kache daemon start # start in background, wait until ready
kache daemon stop # graceful shutdown
kache daemon restart # restart (via launchd/systemd if installed, else manual)
kache daemon run # start in foreground (for debugging)
kache daemon install # install as a system service (launchd/systemd)
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.