# Environment variables

zfin is configured through environment variables. Set them in your
shell, or put them in a `.env` file. The `.env` file is searched first
in the binary's parent directory, then in the current directory; any
value set in the real environment is also honored.

```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.

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

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

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