# 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 <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](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)
