80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](../reference/cli/quote.md) command has
|
|
nothing to serve and reports the symbol as unavailable. Price-history
|
|
commands like [`perf`](../reference/cli/perf.md) and
|
|
[`portfolio`](../reference/cli/portfolio.md) 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](../explanation/caching.md).
|
|
|
|
## Inspecting and clearing the cache
|
|
|
|
```bash
|
|
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`](../reference/cli/cache.md).
|
|
|
|
## See also
|
|
|
|
- [Caching and data freshness](../explanation/caching.md) -- the why.
|
|
- [Data providers and API keys](../reference/providers.md) -- rate limits that shape `force` runs.
|
|
- [Environment variables](../reference/config/environment.md) -- `ZFIN_CACHE_DIR`, `ZFIN_SERVER`.
|
|
|
|
---
|
|
|
|
[Previous: Customize the TUI](customize-the-tui.md) | [Documentation home](../README.md)
|