# 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." One thing the Asset Category axis deliberately does *not* capture is **risk character**. SCHD and QQQ here both land in Equity (`US Large Cap`), yet one rides far calmer than the other -- that distinction lives in [`review`](#review-per-holding-performance-and-risk) below, not in the allocation breakdown. ### 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. ### Spotting a defensive sleeve Asset class tells you what falls in a downturn; the **Vol** and **MaxDD** columns tell you how hard. The two come apart *within* a single asset class. Here SCHD and QQQ are both `US Large Cap`, yet `zfin review` shows SCHD riding far calmer -- its 5-year max drawdown is roughly half QQQ's (about 16% vs. 33%), at a few points lower volatility. QQQ earns more for the bumpier ride (higher return and Sharpe); SCHD trades return for stability. That income/defensive character is *measured* from each fund's own price history -- you don't tag a fund with it, the risk columns reveal it. When several holdings share that profile, give them a common [`bucket::`](classify-holdings.md#fixing-uninformative-sectors) label and sort by sector (`--sort sector`, the default) so they group together and you can read the sleeve's risk character as a whole. ## `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)