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.

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

7.9 KiB Raw Blame History