3.4 KiB
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-fetch every symbol regardless of freshness. Use after a market close, or when you suspect bad cached data. |
never |
Serve cache contents only; make no network calls. True offline mode. |
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. See
zfin cache.
See also
- Caching and data freshness -- the why.
- Data providers and API keys -- rate limits that shape
forceruns. - Environment variables --
ZFIN_CACHE_DIR,ZFIN_SERVER.