68 lines
5.6 KiB
Markdown
68 lines
5.6 KiB
Markdown
# 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)
|