# `zfin cache`

Inspect or clear the local provider-data cache.

```
Usage: zfin cache <stats|stale|clear> | zfin cache refresh [SYMBOL...]
```

| Subcommand | Does                                                                                                                                                       |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `stats`    | List every cached symbol with per-data-type size, age, and freshness state. Stale entries (past TTL) are flagged. Includes `cusip_tickers.srf` if present. |
| `stale`    | Find symbols whose newest candle is behind their peers'. Read-only; reports, never fetches.                                                                 |
| `refresh`  | Force-refresh candle data in the **local** cache, bypassing the TTL and the shared server. No arguments refreshes exactly what `stale` reports.              |
| `clear`    | Delete every file under the cache directory. No confirmation; the next provider call re-fetches everything.                                                 |

The cache directory is `$ZFIN_CACHE_DIR` if set, otherwise
`~/.cache/zfin`.

## `stale` compares against peers, not the clock

A symbol is called stale when other cached symbols **of the same kind**
(equity vs mutual fund) hold a newer bar than it does. That is a
different question from "is this bar old?", and the peer framing is what
makes it trustworthy: an un-modeled market closure moves every symbol
together, so it cannot be mistaken for one frozen cache entry.

## `refresh` deliberately skips the server

`zfin cache refresh` goes straight to the provider. It does **not** ask
`ZFIN_SERVER`, because its job is to repair *your* copy. To refresh the
server's copy instead, use
[`zfin server refresh`](server.md); to find out which side is behind in
the first place, use [`zfin diagnose SYMBOL`](diagnose.md).

## Examples

```bash
zfin cache stats               # what's cached, sizes, and ages
zfin cache stale               # which symbols are behind their peers
zfin cache refresh             # re-fetch exactly what `stale` reported
zfin cache refresh SPY AGG     # re-fetch these two
zfin cache clear               # wipe; everything re-fetches on next use
```

`clear` is safe -- it only removes cached copies of public market data.
Reach for it when you suspect corrupt cached data; routine staleness is
handled automatically by the `auto` refresh policy, and a stale
adjustment basis repairs itself on the next refresh.

## See also

- [Caching and data freshness](../../explanation/caching.md) -- TTLs and the fetch model.
- [Offline use and refreshing data](../../guides/offline-and-refresh.md) -- the `--refresh-data` flag.
- [`diagnose`](diagnose.md) -- trace one symbol through every tier.
- [`server`](server.md) -- refresh the shared server's cache instead.

---

[CLI command reference](index.md)