lobo/zfin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 2 Wiki Activity Actions
zfin/docs/getting-started.md
Emil Lerch 74fc219afd
All checks were successful
Generic zig build / build (push) Successful in 5m48s
Details
Generic zig build / publish-macos (push) Successful in 11s
Details
Generic zig build / deploy (push) Successful in 23s
Details
add docs/guides
2026-06-22 14:53:53 -07:00

8.2 KiB
Raw Blame History

Getting started

This guide takes you from nothing to a working zfin in about ten minutes: install the binary, set one API key, run your first commands on any ticker, then create your own portfolio.

By the end you will have:

  • the zfin binary on your PATH,
  • a free Tiingo API key configured,
  • pulled live quotes and trailing returns for real tickers, and
  • created a minimal portfolio of your own.

1. Install

Option A: pre-built binary (macOS, Apple Silicon)

curl -L -o zfin \
  https://git.lerch.org/api/packages/lobo/generic/zfin-aarch64-macos/latest/zfin-aarch64-macos
chmod +x zfin
sudo mv zfin /usr/local/bin/   # or anywhere on your PATH

Option B: build from source (Linux, macOS)

Building requires Zig 0.16.0. If you use mise, the pinned toolchain installs itself:

git clone https://git.lerch.org/lobo/zfin.git
cd zfin
mise install      # installs Zig 0.16.0 from .mise.toml; skip if you have it
zig build         # binary lands at zig-out/bin/zfin

Put zig-out/bin/zfin on your PATH, or run it by full path.

Verify

zfin version

zfin e246d1e (built 2026-06-19)

2. Get an API key

zfin pulls data from several free-tier providers, but you only need one key to get started:

  • Tiingo (TIINGO_API_KEY) -- daily price history (candles). This is the primary price source and the one key worth setting first. Sign up free at https://tiingo.com.

A couple more are worth adding once you are up and running. None are required for your first run:

Key Unlocks Free signup
POLYGON_API_KEY Dividends and splits (enables total return) https://polygon.io
FMP_API_KEY Earnings history and estimates https://financialmodelingprep.com
ZFIN_USER_EMAIL ETF profiles and enrich (SEC EDGAR requires a contact email -- not a key) your own email

Quotes (Yahoo) and options chains (CBOE) need no key at all. For the full breakdown of who supplies what, see Data providers and API keys.

3. Configure

zfin reads keys from the environment or from a .env file. The .env file is searched first in the binary's parent directory, then in the current directory.

Create a .env (or export the variables in your shell):

TIINGO_API_KEY=your_key_here
ZFIN_USER_EMAIL=you@example.com    # optional, enables ETF profiles

Cached data lands in ~/.cache/zfin by default; override it with ZFIN_CACHE_DIR. See Environment variables for every setting zfin understands.

Not sure a key took, or which features you've unlocked? Run zfin doctor -- it reports which files and keys it found and what each one enables, and changes nothing.

4. Take it for a spin

You don't need a portfolio to use zfin -- point it at any ticker and it fetches what it needs. Start with a live quote (quotes need no API key):

zfin quote SPY

SPY  $746.74  (close)
========================================
  Date:          2026-06-18
  Open:          $747.76
  High:          $748.23
  Low:           $743.86
  Volume:        80,875,657
  Change:        +$5.78 (+0.78%)

(A short price chart prints below the quote. Your figures will differ -- prices move every day.)

The per-symbol commands all work on any ticker, no portfolio required. The first price-history fetch for a symbol populates the cache (a few seconds); later runs are instant:

zfin perf VTI         # 1y/3y/5y/10y trailing returns (needs TIINGO_API_KEY)
zfin history VTI      # last 30 days of prices
zfin divs SCHD        # dividend history       (needs POLYGON_API_KEY)
zfin earnings MSFT    # earnings + estimates   (needs FMP_API_KEY)
zfin etf QQQ          # ETF holdings + sectors (needs ZFIN_USER_EMAIL)
zfin options AAPL     # options chain          (no key)

zfin perf VTI prints Morningstar-style trailing returns:

Trailing Returns for VTI
========================================
Data points: 6290 (2001-05-31 to 2026-06-04)
Latest close: $373.38

As-of 2026-06-04:
                           Price Only   Total Return
---------------------- -------------- --------------
  1-Year Return:              27.29%        28.79%
  3-Year Return:              20.75%        22.22%  ann.
  5-Year Return:              11.22%        12.80%  ann.
  10-Year Return:             13.19%        15.10%  ann.

A command that needs a key you haven't set will say so and name the key -- see the key table in step 2 or Data providers and API keys. Curious what the columns mean? See Returns and performance.

Explore the example portfolios (optional)

Portfolio features -- summaries, allocation breakdowns, retirement projections -- need a portfolio file. To try them before building your own, zfin ships five fictional households under examples/. If you built from source you already have them; with the pre-built binary, clone the repo to get a copy:

git clone https://git.lerch.org/lobo/zfin.git && cd zfin

Point ZFIN_HOME at any example and zfin treats it as your data:

ZFIN_HOME=examples/pre-retirement-both zfin portfolio
ZFIN_HOME=examples/pre-retirement-both zfin analysis
ZFIN_HOME=examples/pre-retirement-both zfin projections

Portfolio Summary (examples/pre-retirement-both/portfolio.srf)
========================================
  Value: $1,383,137.81  Cost: $658,837.01  Gain/Loss: +$724,300.80 (109.9%)
  Lots: 13 open, 0 closed    Positions: 5 symbols
  Historical:  1M: +3.2%  3M: +13.3%  1Y: +24.5%  3Y: +56.4%  5Y: +56.1%  10Y: +182.6%

  Symbol    Shares   Avg Cost      Price     Market Value      Gain/Loss   Weight ...
  ------- -------- ---------- ---------- ---------------- -------------- -------- ...
  AGG        980.0    $115.23     $98.90       $96,922.00 -   $16,002.00     7.0%
  ...

The five households each demonstrate a different planning scenario. To interpret this output see Read your portfolio; for the scenarios themselves see the examples tour and Plan for retirement.

5. Create your own portfolio

A portfolio is a plain-text .srf file: one line per lot (a batch of shares bought on a date). Keep it outside the repository so you never commit real holdings. Make a private directory and a file:

mkdir -p ~/finance
$EDITOR ~/finance/portfolio.srf

A minimal portfolio with two positions and some cash:

#!srfv1
symbol::VTI,shares:num:100,open_date::2020-01-15,open_price:num:170.00,account::My Brokerage
symbol::SCHD,shares:num:200,open_date::2021-06-01,open_price:num:75.00,account::My Brokerage
security_type::cash,shares:num:5000.00,open_date::2026-01-01,open_price:num:1.00,account::My Brokerage

Point zfin at it:

ZFIN_HOME=~/finance zfin portfolio

zfin also auto-detects portfolio.srf in the current directory, so from inside ~/finance you can just run zfin portfolio.

To go further -- options, CDs, illiquid assets, manual prices, ticker aliases, DRIP lots -- see Build your portfolio and the portfolio.srf reference.

6. Open the interactive TUI

Everything the CLI shows is also available in a multi-tab terminal UI:

ZFIN_HOME=~/finance zfin i

Navigate tabs with h/l (or arrow keys), move the cursor with j/k, press ? for the keybinding overlay, and q to quit. See The interactive TUI for the full tour.

Next steps