243 lines
8.2 KiB
Markdown
243 lines
8.2 KiB
Markdown
# 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)
|