---
title: Command reference
description: All kache CLI commands with flags and examples.
---

# 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>]` | 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>] [--top <n>]` | 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 [--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 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`

```sh
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.

```sh
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 nothing
```

If you'd rather wire things up manually, see [Quick start](/docs/getting-started/quick-start#manual-setup-without-kache-init).

---

## `kache monitor`

```sh
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.

```sh
kache monitor --since 24h
```

See [Monitor](/docs/monitor) for a full description of the tabs and fields.

---

## `kache stats`

```sh
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.

```sh
kache stats --since 7d
```

---

## `kache list`

```sh
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.

```sh
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 serde
```

---

## `kache report`

```sh
kache report [--format text|json|markdown|github] [--since <duration>] [--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:

- `hit` means kache restored the artifact without running the compiler.
- `dup` means the cache key missed, the compiler ran, and the compiled bytes already existed in the local store.
- `miss` means 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).

```sh
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
```

The `github` format is friendly for posting as a PR comment via `gh pr comment --body-file`.

---

## `kache save-manifest`

```sh
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](/docs/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 a `Cargo.lock`); it can also be supplied via the `KACHE_NAMESPACE` environment variable, with the flag taking precedence. With no namespace, only the monolithic manifest is uploaded and shard upload is skipped.

```sh
kache save-manifest                           # upload the monolithic manifest only
kache save-manifest --namespace ci-main       # also upload shards, tagged by environment
```

Saving a manifest is cheap; it is safe to run at the end of a CI build alongside `kache sync --push`.

---

## `kache gc`

```sh
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.

```sh
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 build
```

If `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`

```sh
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.

```sh
kache purge                        # wipe everything
kache purge --crate-name tokio     # remove all tokio entries
```

<Callout type="warn">
`kache purge` without a crate name removes your entire local cache. The next build will be a full cold build.
</Callout>

---

## `kache clean`

```sh
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.

![kache clean TUI listing target/ dirs with cached percentages and per-directory breakdown](https://raw.githubusercontent.com/kunobi-ninja/kache/main/assets/clean.gif)

Static layout for reference:

```text
┌ 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                                   │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

```sh
kache clean --dry-run    # preview what would be deleted
kache clean              # delete all target/ directories
```

This is useful for freeing disk space when you're done with a project or before a fresh build.

<Callout type="info">
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.
</Callout>

---

## `kache sync`

```sh
kache sync [--pull] [--push] [--all] [--dry-run] [--manifest-path <path>]
```

Synchronizes the local cache with the configured S3 remote. See [Sync](/docs/remote-cache/sync) for a full walkthrough.

```sh
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 changes
```

---

## `kache why-miss`

```sh
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.

```sh
kache why-miss tokio
```

---

## `kache doctor`

```sh
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:

- `--verify` checks entry, blob, and metadata integrity (orphaned/missing blobs).
- `--checksums` additionally re-hashes blob contents to catch silent corruption (slower; implies `--verify`).
- `--repair` removes corrupted entries and sweeps orphaned blobs (implies `--verify`).

```sh
kache doctor           # diagnose only
kache doctor --fix     # attempt to fix detected issues
kache doctor --verify  # check cache integrity
kache doctor --repair  # remove corrupted entries
```

If you're migrating from sccache, `--fix` handles the migration automatically. `--purge-sccache` additionally removes sccache's cache and binary:

```sh
kache doctor --fix --purge-sccache
```

---

## `kache config`

```sh
kache config
```

Opens 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 daemon`

```sh
kache daemon                  # show daemon status: service install state, running/offline, socket path, log location, daemon version/epoch
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 log
```

See [Daemon lifecycle](/docs/daemon/lifecycle) for details on service installation and the auto-restart behavior.
