# Environment variables

zfin is configured through environment variables. Set them in your
shell, or put them in a `.env` file. Values set in the real environment
always win; a `.env` file supplies anything not already set. The `.env`
file is resolved the same way as your portfolio: when `ZFIN_HOME` is
set, only `$ZFIN_HOME/.env` is read (the current directory is not also
searched); otherwise the `.env` in the current directory is used.

```bash
# .env
TIINGO_API_KEY=your_key
ZFIN_USER_EMAIL=you@example.com
ZFIN_HOME=/home/you/finance
```

To see which of these zfin actually picked up -- and what each one
unlocks -- run [`zfin doctor`](../cli/doctor.md).

## API keys

| Variable             | Provider                | Required for                        | Without it                                                                     |
|----------------------|-------------------------|-------------------------------------|--------------------------------------------------------------------------------|
| `TIINGO_API_KEY`     | Tiingo                  | Daily price history (candles)       | Candles fall back to Yahoo; some symbols (especially mutual funds) won't price |
| `POLYGON_API_KEY`    | Polygon                 | Dividends and splits (total return) | No forward-looking dividends; total returns may use Tiingo's view only         |
| `FMP_API_KEY`        | Financial Modeling Prep | Earnings                            | No earnings data (tab disabled)                                                |
| `TWELVEDATA_API_KEY` | TwelveData              | Quote fallback after Yahoo          | No quote fallback if Yahoo fails                                               |
| `OPENFIGI_API_KEY`   | OpenFIGI                | Faster CUSIP lookups                | CUSIP lookups use slower anonymous rate limits                                 |

None are strictly required; without a given key, that data is simply
unavailable. Quotes (Yahoo) and options (CBOE) need no key. See
[Data providers and API keys](../providers.md) for signup links and
free-tier limits.

## Tiingo plan

`ZFIN_TIINGO_PLAN` is your Tiingo subscription tier (not a key). It
sizes the hourly request budget for **all** Tiingo usage -- candle
history (the main consumer), real-time IEX quotes, and the live stream
-- so a paying subscriber isn't throttled to free-tier limits.

| Variable           | Values           | Default | Effect                                                          |
|--------------------|------------------|---------|-----------------------------------------------------------------|
| `ZFIN_TIINGO_PLAN` | `free` / `power` | `free`  | Hourly Tiingo request cap: free = 50/hour, power = 10,000/hour. |

An unrecognized value logs a warning and falls back to `free`.

## Contact email

| Variable          | Used for                                                                                                                                                                                                              |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ZFIN_USER_EMAIL` | The contact address SEC EDGAR requires in its `User-Agent` header. Enables ETF profiles and [`zfin enrich`](../cli/enrich.md). Not a key -- just your email. Without it, ETF profiles and enrichment are unavailable. |

## Live quotes and streaming

`ZFIN_LIVE_QUOTE_PROVIDER` chooses where intraday quotes come from --
both the `r`/F5 refresh and the opt-in live stream (the `L` toggle on
the TUI's Quote and Portfolio tabs, or [`quote --live`](../cli/quote.md)).

| Variable                   | Values             | Default   | Purpose                                                                                                                  |
|----------------------------|--------------------|-----------|--------------------------------------------------------------------------------------------------------------------------|
| `ZFIN_LIVE_QUOTE_PROVIDER` | `yahoo` / `tiingo` | (derived) | Provider for live quotes + streaming. Unset: derived from the [Tiingo plan](#tiingo-plan) (Power -> Tiingo, else Yahoo). |

- **Yahoo** (default): keyless, works on all tiers, but ~15-minute
  delayed and unofficial (no guarantees).
- **Tiingo**: real-time IEX last-sale (the `tngoLast` reference price);
  requires `TIINGO_API_KEY`. The IEX reference feed works on **any**
  Tiingo tier, free included -- set `ZFIN_LIVE_QUOTE_PROVIDER=tiingo` to
  use it. It's the *automatic* default only on the Power plan, which has
  the request headroom for heavy refresh/streaming use; on the free tier
  it's opt-in (each websocket connect spends one of the 50/hour, but a
  stable stream then costs nothing).

An unrecognized value logs a warning and falls back to the default.

## Paths and directories

| Variable         | Default             | Purpose                                                                                                                                                                                                               |
|------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ZFIN_HOME`      | (current directory) | Directory holding your `portfolio.srf`, `accounts.srf`, `metadata.srf`, `watchlist.srf`, and `.env`. When set, it is consulted **exclusively** for portfolio resolution (the current directory is not also searched). |
| `ZFIN_CACHE_DIR` | `~/.cache/zfin`     | Where fetched provider data is cached.                                                                                                                                                                                |
| `XDG_CACHE_HOME` | --                  | Consulted to build the default cache dir (`$XDG_CACHE_HOME/zfin`) when `ZFIN_CACHE_DIR` is unset.                                                                                                                     |

## Server sync

| Variable      | Purpose                                                                                                                                                                                                                                                     |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ZFIN_SERVER` | Optional URL of a remote [zfin-server](https://git.lerch.org/lobo/zfin-server) instance: a shared cache tier queried between the local cache and the providers. No-ops when unset. See [server sync](../../explanation/caching.md#server-sync-zfin_server). |
| `ZFIN_SERVER_API_KEY` | Optional API key sent as the `X-API-Key` header on every `ZFIN_SERVER` request. Set it when the server requires auth for cache endpoints; leave unset for an open server. No-ops when `ZFIN_SERVER` is unset. |

## Output

| Variable   | Purpose                                                                                                                                         |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `NO_COLOR` | When set (to any value), disables colored output, per the [no-color.org](https://no-color.org) convention. Equivalent to the `--no-color` flag. |

## See also

- [Getting started](../../getting-started.md) -- the initial setup.
- [`zfin doctor`](../cli/doctor.md) -- reports which variables are set and what each enables.
- [Data providers and API keys](../providers.md) -- where to get each key.
- [Offline use and refreshing data](../../guides/offline-and-refresh.md) -- the `--refresh-data` cache policy.

---

[Documentation home](../../README.md#reference)
