76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# `zfin snapshot`
|
|
|
|
Compute a portfolio snapshot and write it to `history/` -- the building
|
|
block of your value time series.
|
|
|
|
```
|
|
Usage: zfin snapshot [opts]
|
|
```
|
|
|
|
By default, refreshes candles for held symbols, derives the as-of date
|
|
from the cached candle dates, prices each lot at the close on or before
|
|
that date, and writes `history/<as_of_date>-portfolio.srf` atomically.
|
|
The file is a discriminated SRF whose records start with
|
|
`kind::<meta|total|tax_type|account|lot>`.
|
|
|
|
## Options
|
|
|
|
| Flag | Effect |
|
|
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `--dry-run` | Compute and print to stdout; write nothing. |
|
|
| `--force` | Overwrite an existing snapshot for the date. |
|
|
| `--out <path>` | Override the output path. |
|
|
| `--as-of <DATE>` | Write a snapshot for a historical date (uses git to recover state and the candle cache for pricing). Accepts `YYYY-MM-DD` or `1W`/`1M`/`1Q`/`1Y`. |
|
|
|
|
If the target file already exists and `--force` isn't passed, the run
|
|
skips with a stderr message.
|
|
|
|
## What gets written
|
|
|
|
Each snapshot is a **valuation** record for one date, in two layers:
|
|
|
|
| Record kind | Contents |
|
|
|----------------------|--------------------------------------------------------------|
|
|
| `meta` | As-of date, capture time, zfin version, quote-date span, stale-quote count. |
|
|
| `total` | `net_worth`, `liquid`, `illiquid`. **Authoritative** totals. |
|
|
| `tax_type` | Value per tax treatment (Traditional, Roth, Taxable, HSA). |
|
|
| `account` | Value per account. |
|
|
| `lot` | Per-lot decomposition: symbol, account, security type, shares, open price, cost basis, price, value, quote date/staleness. |
|
|
|
|
Two things to know before reading `lot` rows:
|
|
|
|
- The `total` rows are authoritative. Lot rows are a decomposition aid
|
|
and do not carry portfolio-level adjustments, so summing them is not
|
|
guaranteed to reproduce `total::liquid` exactly.
|
|
- What `shares`, `open_price`, `cost_basis`, and `value` *mean* differs
|
|
by security type, and so do the relationships between them. In
|
|
particular, a stock lot's `shares` is the raw as-transacted count
|
|
while its `value` is split-adjusted, so `shares * price` is not
|
|
generally `value`.
|
|
|
|
A snapshot deliberately omits most of a lot's detail -- it is not a
|
|
lot-level record. [The snapshot model](../../explanation/snapshots-model.md)
|
|
covers the full field semantics, what is left out, and why.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
zfin snapshot --dry-run # preview today's snapshot
|
|
zfin snapshot # write history/<today>-portfolio.srf
|
|
zfin snapshot --as-of 2025-01-02 # back-fill a past date
|
|
```
|
|
|
|
Automate with cron for a self-building series:
|
|
|
|
```cron
|
|
0 18 * * 1-5 cd ~/finance && /usr/local/bin/zfin snapshot
|
|
```
|
|
|
|
## See also
|
|
|
|
- [Snapshots and history](../../guides/snapshots-and-history.md) -- the workflow.
|
|
- [`history`](history.md) / [`compare`](compare.md) -- read the snapshots back.
|
|
|
|
---
|
|
|
|
[CLI command reference](index.md)
|