zfin/docs/reference/cli/cache.md

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; to find out which side is behind in the first place, use zfin diagnose SYMBOL.

Examples

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 -- TTLs and the fetch model.
• Offline use and refreshing data -- the --refresh-data flag.
• diagnose -- trace one symbol through every tier.
• server -- refresh the shared server's cache instead.

---

CLI command reference