103 lines
6.1 KiB
Markdown
103 lines
6.1 KiB
Markdown
# 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/`](../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:
|
|
|
|
```bash
|
|
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](getting-started.md) -- install, set up API keys,
|
|
create your first portfolio, run your first commands, open the TUI.
|
|
2. [Core concepts](explanation/concepts.md) -- 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](guides/set-up-your-portfolio.md) | Write a `portfolio.srf` from scratch: lots, cash, options, CDs |
|
|
| [Classify your holdings](guides/classify-holdings.md) | Create `metadata.srf` (by hand or with `enrich`) so analysis works |
|
|
| [Map your accounts](guides/set-up-accounts.md) | Tag accounts with tax type and institution in `accounts.srf` |
|
|
| [Read your portfolio](guides/read-your-portfolio.md) | Interpret `portfolio`, `analysis`, `exposure`, `review`, `perf` |
|
|
| [Track contributions](guides/track-contributions.md) | See money added over time and tag internal transfers |
|
|
| [Snapshots and history](guides/snapshots-and-history.md) | Record daily snapshots and compare your portfolio over time |
|
|
| [Plan for retirement](guides/plan-retirement.md) | Configure `projections.srf` for accumulation and drawdown |
|
|
| [Audit against your brokerage](guides/audit-against-brokerage.md) | Reconcile zfin against Fidelity/Schwab/Wells exports |
|
|
| [A periodic review](guides/periodic-review.md) | Reconcile, see what changed, then commit the new baseline |
|
|
| [Customize the TUI](guides/customize-the-tui.md) | Rebind keys and recolor the interface |
|
|
| [Offline use and refreshing data](guides/offline-and-refresh.md) | Control caching and provider calls |
|
|
|
|
## Reference
|
|
|
|
Look-it-up material. Exhaustive, terse, and kept in step with the
|
|
shipped binary.
|
|
|
|
- [CLI command reference](reference/cli/index.md) -- every command,
|
|
its flags, and sample output.
|
|
- Configuration files:
|
|
- [`portfolio.srf`](reference/config/portfolio-srf.md) -- positions, lots, cash, options, CDs
|
|
- [`metadata.srf`](reference/config/metadata-srf.md) -- sector / geography / asset-class classification
|
|
- [`accounts.srf`](reference/config/accounts-srf.md) -- tax type and institution per account
|
|
- [`projections.srf`](reference/config/projections-srf.md) -- retirement projection inputs
|
|
- [`watchlist.srf`](reference/config/watchlist-srf.md) -- price-only symbols
|
|
- [`transaction_log.srf`](reference/config/transaction-log-srf.md) -- declared transfers
|
|
- [`keys.srf`](reference/config/keys-srf.md) -- TUI keybindings
|
|
- [`theme.srf`](reference/config/theme-srf.md) -- TUI colors
|
|
- [Environment variables](reference/config/environment.md) -- API keys, `ZFIN_HOME`, `ZFIN_CACHE_DIR`, and more
|
|
- [The interactive TUI](reference/tui.md) -- tabs, keybindings, theming.
|
|
- [Data providers and API keys](reference/providers.md) -- who supplies
|
|
what, free-tier limits, and where to get keys.
|
|
|
|
## Explanation
|
|
|
|
Background and the "why" behind zfin's behavior.
|
|
|
|
- [Core concepts](explanation/concepts.md)
|
|
- [Caching and data freshness](explanation/caching.md)
|
|
- [Why multiple data providers](explanation/data-providers.md)
|
|
- [Returns and performance](explanation/returns-and-performance.md)
|
|
- [The retirement projection model](explanation/projections-model.md)
|
|
- [FAQ and troubleshooting](explanation/faq-troubleshooting.md)
|
|
|
|
## 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`](../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.
|