zfin/docs/guides/offline-and-refresh.md

Offline use and refreshing data

Goal: control when zfin talks to the network -- force a full refresh, work entirely offline, or rely on normal cache freshness.

zfin caches every fetch under ~/.cache/zfin (override with ZFIN_CACHE_DIR) and reuses it until it goes stale. The global --refresh-data flag overrides that policy for a single run.

The three policies

--refresh-data must appear before the subcommand:

zfin --refresh-data=auto   portfolio     # default
zfin --refresh-data=force  perf VTI
zfin --refresh-data=never  analysis

Value	Behavior
auto (default)	Respect each data type's cache TTL; fetch only what's stale.
force	Re-ask providers regardless of freshness. Use after a market close, or when a fetch seems to have been missed.
never	Serve cache contents only; make no network calls. True offline mode.

force tops up price history, it does not rebuild it

Worth knowing before you reach for it: for daily candles, force skips the TTL and asks the provider for anything newer than the last cached bar. It does not re-download the series. So if you suspect the existing bars are wrong rather than merely incomplete, force will not help -- it appends and moves on.

That case is handled automatically now. When a dividend or split goes ex, the bars behind it need their adjusted closes marked down, and zfin re-downloads that symbol's full history to pick up the corrected values on its own -- see Incremental candle updates. zfin diagnose SYMBOL says whether one is pending.

zfin cache clear remains the blunt instrument if you want to discard everything and start over.

Working offline

--refresh-data=never is the way to run on a plane or to get deterministic output from already-cached data. Anything not in the cache simply isn't shown:

ZFIN_HOME=examples/pre-retirement-both zfin --refresh-data=never analysis

Note that quotes are never cached (they're meant to be live), so in never mode the quote command has nothing to serve and reports the symbol as unavailable. Price-history commands like perf and portfolio work fine offline once their candles are cached.

How freshness works

In auto mode, each data type has its own time-to-live:

Data	TTL
Daily candles	~24 hours
Dividends / splits	14 days
Options	1 hour
Earnings	30 days (refreshed early once a result is due)
ETF profiles	~30 days
Quotes	never cached

So a second portfolio run the same day is instant and network-free without any flag. For the full rationale, see Caching and data freshness.

Inspecting and clearing the cache

zfin cache stats      # what's cached, sizes, and ages
zfin cache clear      # delete all cached data

cache clear is safe -- everything re-fetches on the next run (subject to provider rate limits). Reach for it only when you suspect corrupt cached data; normal staleness is handled by auto, and a stale adjustment basis repairs itself. See zfin cache.

See also

• Caching and data freshness -- the why.
• Data providers and API keys -- rate limits that shape force runs.
• Environment variables -- ZFIN_CACHE_DIR, ZFIN_SERVER.

---

Previous: Customize the TUI | Documentation home