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