# Read your portfolio

**Goal:** make sense of what zfin shows you. This guide walks the five
commands you'll reach for most -- `portfolio`, `analysis`, `review`,
`exposure`, and `perf` -- and explains how to read each one.

Every example below runs against the bundled
[`pre-retirement-both`](../../examples/pre-retirement-both/) household,
so you can follow along verbatim:

```bash
ZFIN_HOME=examples/pre-retirement-both zfin portfolio
```

(Dollar figures depend on live prices, so yours will differ.)

## `portfolio`: positions and value

```bash
ZFIN_HOME=examples/pre-retirement-both zfin portfolio
```

```
Portfolio Summary (examples/pre-retirement-both/portfolio.srf)
========================================
  Value: $1,383,137.81  Cost: $658,837.01  Gain/Loss: +$724,300.80 (109.9%)
  Lots: 13 open, 0 closed    Positions: 5 symbols
  Historical:  1M: +3.2%  3M: +13.3%  1Y: +24.5%  3Y: +56.4%  5Y: +56.1%  10Y: +182.6%

  Symbol    Shares   Avg Cost      Price     Market Value      Gain/Loss   Weight ...
  VTI       2480.0    $138.35    $373.38      $925,982.40 +  $582,874.40    66.9%
    open      1100.0    $140.00                 $410,718.00 +  $256,718.00          2018-06-15 LT Pat 401k
    ...
```

How to read it:

- **The header line** is your liquid total, total cost, and aggregate
  gain/loss.
- **Historical** is the portfolio's blended price return over trailing
  windows -- a quick "how have my holdings done" gut check.
- **Each position** shows aggregated shares, average cost, current
  price, market value, gain/loss, and weight. Indented `open` rows are
  the individual lots, tagged **LT**/**ST** (long/short-term holding
  period) and the account.
- **Cash** is summarized by account at the bottom.

Manual-priced rows render in warning color so you know the price may be
stale. Full output shape: [`zfin portfolio`](../reference/cli/portfolio.md).

### Covered calls

zfin values a written (short) call by **capping the covered shares at
the strike**, rather than pricing the option contract -- it never looks
up a live option quote. When the call is in-the-money (the stock trades
above the strike), the covered shares are valued at the strike, since
that's the price you'd be assigned at; an out-of-the-money call gets no
adjustment, and an expired or closed call stops capping.

This differs from your brokerage, which tracks the call as its own line
with its own mark-to-market gain/loss. Example: you hold 100 MSFT and
wrote a $500 call. If MSFT trades at $510, zfin values those shares at
**$50,000** (100 x the $500 strike), not $51,000 (100 x $510) -- the
$1,000 of upside above the strike now belongs to the call holder. A
brokerage would instead show $51,000 of stock plus a separate,
losing short-call position.

This is deliberate, and for a covered call used as an exit strategy
it's the more useful number: the cap is the value you'll actually
realize when the call assigns. Mark-to-market would understate it,
because an in-the-money call also carries time value you'd only pay to
*buy it back* -- which a let-it-assign writer never does. (At $510 the
call might mark around $14, so a brokerage nets $496/share even though
you'll realize the full $500 at assignment.) The flip side: zfin is
built for covered-call and buy-write investors, not active option
trading -- it deliberately doesn't track the live mark-to-market swings
of contracts you intend to trade rather than hold to assignment.

## `analysis`: allocation breakdowns

```bash
ZFIN_HOME=examples/pre-retirement-both zfin analysis
```

`analysis` answers "how is my money allocated?" along five axes:
**Asset Category**, **Sector**, **Geographic**, **By Account**, and
**By Tax Type**. Each bar is a share of your liquid total.

```
  By Tax Type
  Traditional (Pre-Tax)    █████████████████▋              58.9%  $815,290.06
  Taxable                  ██████▍                         21.6%  $299,010.60
  Roth (Post-Tax)          █████                           16.9%  $233,732.95
  HSA (Triple Tax-Free)    ▊                                2.5%  $35,104.20
```

The Sector and Asset Category axes need [`metadata.srf`](classify-holdings.md);
the Tax Type axis needs [`accounts.srf`](set-up-accounts.md). Anything
missing classification lands under "Unclassified" / "Unknown."

### Umbrella exposure

A personal **umbrella insurance** policy covers liability -- lawsuits
and judgments -- above your auto/home limits, and you size it to the
assets you'd need to protect. The last block estimates that target: how
much of your liquid net worth is **exposed** to a civil judgment
because it sits outside judgment-protected retirement accounts:

```
  Umbrella exposure
    Total liquid:                              $1,383,137.81
    Shielded (retirement accounts):            $1,084,127.21
    Exposed (taxable + non-shielded pre-tax):  $299,010.60 (21.6%)
                                               ↑ approximate umbrella target
```

The default rule treats anything that isn't `taxable` as shielded.
Override per account with `shielded:bool:false` in
[`accounts.srf`](set-up-accounts.md#4-advanced-flags) -- IRA protection
varies by state and isn't modeled automatically.

## `review`: per-holding performance and risk

```bash
ZFIN_HOME=examples/pre-retirement-both zfin review
```

`review` is a dashboard: one row per holding with trailing returns,
volatility, Sharpe ratio, max drawdown, and a taxable-percentage
column, plus automated **findings** at the bottom.

```
  Symbol   Sector                   Wt%       1Y       3Y  ...   3Y-SR   10Y-SR   5Y-MaxDD    Tax%
  VTI      Diversified            66.9%   +30.2%   +23.3%  ...    1.29     0.90      24.8%   10.9%
  QQQ      Technology              3.5%   +43.1%   +29.3%  ...    1.41     1.16      32.6%    0.0%

  Findings (2 active, 0 acked, 0 resolved)
  ⚠️ VTI at 66.9% of liquid (warn at 50.0%, flag at 70.0%)
  ❌️ Diversified sector at 85.7% (warn at 60.0%, flag at 75.0%)
```

The findings flag concentration, sector dominance, volatility
outliers, and tiny positions against configurable thresholds. The
status icons at the top summarize which checks fired. See
[`zfin review`](../reference/cli/review.md).

### Acknowledging findings

Findings are re-derived every run, so one you've already judged
acceptable would otherwise nag you forever. Acknowledge it to record
*why* and drop it from the active list. This is an interactive step --
in the [TUI](../reference/tui.md) Review tab, move the cursor to a
finding and press:

- **`a`** -- acknowledge it (you can type a short reason, saved as a note).
- **`U`** -- un-acknowledge (return it to the active list).
- **`v`** -- toggle whether already-acknowledged findings are shown.

(Those are the defaults; `?` shows your current bindings.)
Acknowledgments persist in
[`acknowledgments.srf`](../reference/config/acknowledgments-srf.md)
beside your portfolio, so they survive across runs and are versioned
with the rest of your data. The CLI honors them -- `zfin review
--show-acked` includes acked findings in the table -- but only the TUI
can add or remove them.

## `exposure`: look-through to a single symbol

```bash
ZFIN_HOME=examples/pre-retirement-both zfin exposure SPY
```

`exposure` answers "how much of *X* do I really own?" -- combining
direct holdings with look-through into the ETFs you hold (matched by
CUSIP against each ETF's latest reported holdings):

```
Exposure to SPY  (examples/pre-retirement-both/portfolio.srf)
========================================
  Total exposure    17.3%     $238,956.80
    Direct          17.3%     $238,956.80
    Look-through     0.0%           $0.00
```

This is most interesting for an individual stock you also hold inside
broad-market ETFs (e.g. checking your true NVDA exposure across VTI,
SPY, and QQQ). See [`zfin exposure`](../reference/cli/exposure.md).

## `perf`: trailing returns for one symbol

```bash
ZFIN_HOME=examples/pre-retirement-both zfin perf VTI
```

`perf` shows Morningstar-style trailing returns (price-only **and**
total return), as-of the latest close and as-of the most recent
month-end, plus risk metrics. For what "total return," "annualized,"
and "month-end" mean, see
[Returns and performance](../explanation/returns-and-performance.md).

## Where to go next

- Track change over time: [Snapshots and history](snapshots-and-history.md)
- See money added: [Track contributions](track-contributions.md)
- Look ahead: [Plan for retirement](plan-retirement.md)
- Command details: the [CLI reference](../reference/cli/index.md)

---

[Previous: Map your accounts](set-up-accounts.md) | [Next: Track contributions](track-contributions.md) | [Documentation home](../README.md)
