lobo/zfin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 2 Wiki Activity Actions
zfin/docs/reference/config/environment.md
Emil Lerch bd6bc1d161
All checks were successful
Generic zig build / build (push) Successful in 5m0s
Details
Generic zig build / deploy (push) Successful in 25s
Details
Generic zig build / publish-macos (push) Successful in 47s
Details
prefer ZFIN_HOME for .env, match portfolio loading paradigm
2026-07-01 10:49:02 -07:00

8.1 KiB
Raw Blame History

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.

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

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

Variable Values Default Purpose
ZFIN_LIVE_QUOTE_PROVIDER yahoo / tiingo (derived) Provider for live quotes + streaming. Unset: derived from the 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 instance: a shared cache tier queried between the local cache and the providers. No-ops when unset. See server sync.
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 convention. Equivalent to the --no-color flag.

See also

Documentation home