zfin/docs/guides/set-up-your-portfolio.md

# Build your portfolio

**Goal:** create a `portfolio.srf` that captures your holdings -- the
shares you own, what you paid, and which account each lot lives in.
Everything else in zfin reads from this file.

**You'll need:** a text editor and a private directory outside the
repo (so you never commit real holdings). This guide builds up a file
much like the one in
[`examples/pre-retirement-both`](../../examples/pre-retirement-both/portfolio.srf);
the full field list lives in the
[`portfolio.srf` reference](../reference/config/portfolio-srf.md).

You only need this one file to begin. `accounts.srf`, `metadata.srf`,
`projections.srf`, and the rest are optional add-ons you layer on as
you need them -- zfin works without them, just with fewer breakdowns
(see [the `.srf` files overview](../explanation/concepts.md#the-srf-files)).

## Key terms

Three words show up throughout zfin, nesting from smallest to largest:

- **Share** -- one unit of a security (a stock, ETF, or fund); the atom
  of ownership.
- **Lot** -- one purchase: a batch of shares of a single security,
  bought on one date at one price, in one account. A lot is the unit of
  a `portfolio.srf` line. zfin tracks lots rather than running totals so
  it can derive each lot's cost basis, holding period (short- vs
  long-term), and gain/loss.
- **Position** (or **holding**) -- all the lots of the same security
  rolled together **across every account**: total shares, average cost,
  and market value. Your VTI shows as a single position even when it's
  spread across a 401(k), a Roth IRA, and a taxable brokerage -- a
  whole-household, cross-account rollup most brokerages won't show you,
  and a core reason to run zfin. It's one row in the portfolio summary,
  with its lots indented beneath.

In short: you record **lots** (one per line) and zfin aggregates them
into **positions** for display.

## 1. Start the file

A portfolio is one lot per line -- one purchase. Create
`~/finance/portfolio.srf`:

```srf
#!srfv1
symbol::VTI,shares:num:1100,open_date::2018-06-15,open_price:num:140.00,account::Pat 401k
```

The `#!srfv1` header is required. Each line is comma-separated
`key::value` pairs; numbers use `key:num:value`.

Check it:

```bash
ZFIN_HOME=~/finance zfin portfolio
```

## 2. Add more lots

Add one line per purchase. Multiple lots of the same symbol aggregate
into a single position automatically, so record each buy at its own
cost basis rather than averaging by hand:

```srf
#!srfv1
symbol::VTI,shares:num:1100,open_date::2018-06-15,open_price:num:140.00,account::Pat 401k
symbol::VTI,shares:num:240,open_date::2015-01-08,open_price:num:103.40,account::Pat Roth
symbol::AGG,shares:num:600,open_date::2020-01-10,open_price:num:115.50,account::Pat 401k
symbol::QQQ,shares:num:65,open_date::2019-11-22,open_price:num:200.10,account::Pat Roth
```

zfin shows each position with its lots, market value, and gain/loss:

```
  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
    open       240.0    $103.40                  $89,611.20 +   $64,795.20          2015-01-08 LT Pat Roth
```

## 3. Record cash

Cash, money-market, and settlement balances are lots with
`security_type::cash`. They need no symbol, open date, or price:

```srf
security_type::cash,shares:num:48000.00,open_date::2026-04-30,open_price:num:1.00,account::Joint taxable
```

Cash is grouped by account in its own section of the portfolio
summary.

## 4. Use accounts consistently

The `account::` value is just a label, but it has to match **exactly**
across lots (and later in [`accounts.srf`](set-up-accounts.md)). Pick
names and reuse them verbatim: `Pat 401k`, `Joint taxable`,
`Family HSA`. Account names drive the By-Account and (with
`accounts.srf`) the By-Tax-Type breakdowns in
[`zfin analysis`](read-your-portfolio.md).

## 5. Special holdings

zfin handles more than stocks and cash. Each is one line; see the
[reference](../reference/config/portfolio-srf.md) for full field
lists:

- **Sold positions** -- add `close_date` and `close_price` to a lot.
- **Options** -- `security_type::option` with a readable symbol plus
  explicit `option_type` / `underlying` / `strike` / `maturity_date`
  fields; negative `shares` to write (sell) a contract. See the
  covered-call example below.
- **CDs** -- `security_type::cd` with `maturity_date` and `rate`.
- **Illiquid assets** (home, vehicle) -- `security_type::illiquid`;
  counted in Net Worth but not the liquid total.
- **Securities the providers don't cover** (e.g. a 401k CIT share
  class) -- add a manual `price::` and `price_date::`, or a
  `ticker::` alias for pricing. See
  [price resolution](../reference/config/portfolio-srf.md#price-resolution).

### Example: a covered call

Options trip people up, so here's a worked one. A *covered call* is two
lots -- the shares you own, plus one call you write (sell) against them.
Say you hold 100 shares of MSFT and sell a call:

```srf
#!srfv1
# The 100 shares you own -- the "covered" part
symbol::MSFT,shares:num:100,open_date::2024-02-01,open_price:num:400.00,account::Joint taxable
# One call written against them
security_type::option,symbol::MSFT 06/19/2026 500.00 C,shares:num:-1,open_date::2026-01-15,open_price:num:6.68,option_type::call,underlying::MSFT,strike:num:500,maturity_date::2026-06-19,account::Joint taxable
```

Reading the option lot:

- **`shares:num:-1`** -- you *wrote* one contract; negative means short
  (sold). Each contract covers 100 shares.
- **`open_price:num:6.68`** -- the premium you received, per share
  ($6.68 x 100 = $668 for the contract).
- **`option_type` / `underlying` / `strike` / `maturity_date`** define
  the contract. `symbol` is just a human-readable label -- use whatever
  your brokerage shows (here `MSFT 06/19/2026 500.00 C`).
- It's "covered" because the 100 MSFT shares in the same account back
  the call. When it's closed or expires, add `close_date` and
  `close_price` (use `0` if it expired worthless and you kept the
  premium).

**zfin values this differently from your brokerage.** Your brokerage
tracks the call as its own security with its own gain/loss. zfin
doesn't price the contract at all; instead it caps the covered shares
at the strike while the call is in-the-money. So if MSFT trades at $510
here, zfin values these 100 shares at **$50,000** (the $500 strike),
not $51,000 -- the upside above the strike belongs to the call holder.
See [covered-call valuation](read-your-portfolio.md#covered-calls) for
the full rule.

## 6. Optional: split across multiple files

You can keep holdings in several files -- `portfolio.srf`,
`portfolio_401k.srf`, `portfolio_taxable.srf`. zfin union-merges every
`portfolio*.srf` in `ZFIN_HOME` by default, so the CLI and TUI both see
one combined view. Target a subset with `-p`:

```bash
zfin -p 'portfolio_*.srf' portfolio      # quote the glob so the shell doesn't expand it
zfin -p portfolio.srf -p portfolio_hsa.srf portfolio
```

**A good first split: closed positions.** When you sell, move the
closed (sold) lots into a `portfolio_closed_positions.srf`. Your main
`portfolio.srf` then shows only what you currently hold, while the sold
lots still merge in -- so realized gain/loss and back-dated
(`--as-of`) snapshots stay accurate. Because the filename matches
`portfolio*.srf`, it's picked up automatically -- no flag needed.

```srf
#!srfv1
# Sold lots live here so portfolio.srf stays focused on current holdings.
symbol::AMZN,shares:num:10,open_date::2022-03-15,open_price:num:150.25,close_date::2024-01-15,close_price:num:185.50,account::Joint taxable
```

## Next steps

- [Classify your holdings](classify-holdings.md) so analysis can break
  down your allocation.
- [Map your accounts](set-up-accounts.md) to unlock the tax-type view.
- [Read your portfolio](read-your-portfolio.md) to interpret the output.

---

[Next: Classify your holdings](classify-holdings.md) | [Documentation home](../README.md)