# 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)