zfin/docs

zfin documentation

zfin is a financial-data CLI and terminal UI for tracking a real portfolio, analyzing trailing returns and risk, and running retirement projections -- all from the terminal.

These docs are task-first. Almost every example here is runnable against the fictional example portfolios that ship in the repo under examples/, so you can follow along verbatim and see the exact output shown. Set ZFIN_HOME to an example directory and any command reads that portfolio:

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

If you are reading these on Forgejo, every link below is a relative path you can click.

Start here

New to zfin? Read these in order:

1. Getting started -- install, set up API keys, create your first portfolio, run your first commands, open the TUI.
2. Core concepts -- the handful of ideas (the .srf files, ZFIN_HOME, live vs. snapshot data) that make everything else click.

The user manual (workflows)

Goal-oriented guides. Each one walks an end-to-end task against a real example portfolio and links to the reference for exhaustive detail.

Guide	What you'll accomplish
Build your portfolio	Write a portfolio.srf from scratch: lots, cash, options, CDs
Classify your holdings	Create metadata.srf (by hand or with enrich) so analysis works
Map your accounts	Tag accounts with tax type and institution in accounts.srf
Read your portfolio	Interpret portfolio, analysis, exposure, review, perf
Track contributions	See money added over time and tag internal transfers
Snapshots and history	Record daily snapshots and compare your portfolio over time
Plan for retirement	Configure projections.srf for accumulation and drawdown
Audit against your brokerage	Reconcile zfin against Fidelity/Schwab/Wells exports
A periodic review	Reconcile, see what changed, then commit the new baseline
Customize the TUI	Rebind keys and recolor the interface
Offline use and refreshing data	Control caching and provider calls

Reference

Look-it-up material. Exhaustive, terse, and kept in step with the shipped binary.

• CLI command reference -- every command, its flags, and sample output.
• Configuration files:
  • portfolio.srf -- positions, lots, cash, options, CDs
  • metadata.srf -- sector / geography / asset-class classification
  • accounts.srf -- tax type and institution per account
  • projections.srf -- retirement projection inputs
  • watchlist.srf -- price-only symbols
  • transaction_log.srf -- declared transfers
  • acknowledgments.srf -- acknowledged review findings
  • keys.srf -- TUI keybindings
  • theme.srf -- TUI colors
  • Environment variables -- API keys, ZFIN_HOME, ZFIN_CACHE_DIR, and more
• The interactive TUI -- tabs, keybindings, theming.
• Data providers and API keys -- who supplies what, free-tier limits, and where to get keys.

Explanation

Background and the "why" behind zfin's behavior.

• Core concepts
• Caching and data freshness
• Why multiple data providers
• Returns and performance
• The retirement projection model
• FAQ and troubleshooting

The example portfolios

The guides lean on five bundled, fictional households. They are safe to read, copy, and run against:

ZFIN_HOME=examples/...	Household	Demonstrates
pre-retirement-both	Pat & Sam, ~45, ~$1.3M, contributing	A target retirement date and a target spending level
pre-retirement-age	same household	A target retirement date only
pre-retirement-spending	same household	A target spending level only (earliest-retirement search)
pre-retirement-spending-target	same household	An explicit, deliberately infeasible planning anchor
post-retirement	Robin & Jamie, ~68, ~$2.5M, drawing down	Distribution-only planning, with snapshot history

See examples/README.md for the full tour of what differs between them.

A note on the examples and your real data

All names, share counts, account numbers, and prices in examples/ are fictional. Nothing in these docs is financial advice. When you point zfin at your own data, keep it outside the repository (set ZFIN_HOME to a private directory) so you never commit real holdings.