106 lines
8.1 KiB
Markdown
106 lines
8.1 KiB
Markdown
# 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)
|