100 lines
4.3 KiB
Markdown
100 lines
4.3 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-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](../explanation/caching.md#incremental-candle-updates).
|
|
[`zfin diagnose SYMBOL`](../reference/cli/diagnose.md) 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:
|
|
|
|
```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`, and a stale
|
|
adjustment basis repairs itself. 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)
|