# `zfin compare`

Compare your portfolio at two points in time: liquid totals,
per-symbol price moves, and contribution attribution.

```
Usage:
  zfin compare <DATE>             # compare DATE vs. live portfolio
  zfin compare <DATE1> <DATE2>    # compare two historical dates
```

Arguments can be given in any order; output always reads older ->
newer. Dates accept `YYYY-MM-DD` or relative shortcuts
(`1W`/`1M`/`1Q`/`1Y`). Historical dates resolve against your
`history/*-portfolio.srf` snapshots; on a missing date, `compare`
prints the nearest available dates and exits rather than snapping
silently.

## Options

| Flag                                                   | Effect                                                                                                                                |
|--------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| `--projections`                                        | Add projected-return and 99% safe-withdrawal deltas (adds ~1-2s per endpoint).                                                        |
| `--no-events`                                          | With `--projections`, exclude life events.                                                                                            |
| `--snapshot-before <DATE>` / `--snapshot-after <DATE>` | Override a side's snapshot (`--snapshot-after live` for the current portfolio).                                                       |
| `--commit-before <SPEC>` / `--commit-after <SPEC>`     | Pin the git commit for the attribution block (`HEAD`, `HEAD~N`, SHA, or `working`). Useful when a review date and its commit diverge. |

## Example

```bash
ZFIN_HOME=examples/post-retirement zfin compare 2024-04-01 2025-04-01
```

```
Portfolio comparison: 2024-04-01 → 2025-04-01 (365 days)

Liquid:  $2,350,000.00 → $2,580,000.00    +$230,000.00   +9.79%
```

With symbols held on both dates, a per-symbol price-change table
appears, sorted by percentage move.

## See also

- [Snapshots and history](../../guides/snapshots-and-history.md)
- [`history`](history.md) -- the full timeline. [`contributions`](contributions.md) -- the attribution detail.

---

[CLI command reference](index.md)
