# `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.

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