# 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) ```bash 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](https://mise.jdx.dev/), the pinned toolchain installs itself: ```bash 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 ```bash 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 . 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) | | | `FMP_API_KEY` | Earnings history and estimates | | | `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](reference/providers.md). ## 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): ```bash 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](reference/config/environment.md) for every setting zfin understands. Not sure a key took, or which features you've unlocked? Run [`zfin doctor`](reference/cli/doctor.md) -- 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): ```bash 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: ```bash 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](#2-get-an-api-key) or [Data providers and API keys](reference/providers.md). Curious what the columns mean? See [Returns and performance](explanation/returns-and-performance.md). ### 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: ```bash git clone https://git.lerch.org/lobo/zfin.git && cd zfin ``` Point `ZFIN_HOME` at any example and zfin treats it as your data: ```bash 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](guides/read-your-portfolio.md); for the scenarios themselves see [the examples tour](../examples/README.md) and [Plan for retirement](guides/plan-retirement.md). ## 5. Create your own portfolio A portfolio is a plain-text [`.srf`](reference/config/portfolio-srf.md) 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: ```bash mkdir -p ~/finance $EDITOR ~/finance/portfolio.srf ``` A minimal portfolio with two positions and some cash: ```srf #!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: ```bash 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](guides/set-up-your-portfolio.md) and the [`portfolio.srf` reference](reference/config/portfolio-srf.md). ## 6. Open the interactive TUI Everything the CLI shows is also available in a multi-tab terminal UI: ```bash 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](reference/tui.md) for the full tour. ## Next steps - **Understand the model:** [Core concepts](explanation/concepts.md) - **Build out your data:** [Classify your holdings](guides/classify-holdings.md) and [Map your accounts](guides/set-up-accounts.md) - **Plan ahead:** [Plan for retirement](guides/plan-retirement.md) - **Browse everything:** the [documentation home](README.md)