Snapshot
Record your portfolio value at a point in time. Snapshots let you track how total market value and individual positions evolve day by day.
firma add snapshot
Syncs prices from Finnhub and records the current market value of every
holding into a local snapshot table. Run it once a day (or on demand)
to build a portfolio value time series.
$firma add snapshot
Syncing prices...
✓Snapshot recorded for 2026-04-26: 4 holdings.
Requires a Finnhub API key. Set it once with
firma config set finnhub-key <key>.
Snapshots are stored in ~/.firma/firma.db and never overwritten
for the same date unless you re-run on the same day.firma show snapshot
Without a ticker: shows total portfolio market value per day as an ASCII
bar chart with delta vs the previous day.
Use
--from and --to to narrow the date range.
Add -c USD to convert amounts to a foreign currency.$firma show snapshot
| DATE | TOTAL MARKET VALUE | ||
|---|---|---|---|
| 2026-04-20 | ━━━━━━━━━━━━━━━━━━━━──── | $143,218 | |
| 2026-04-21 | ━━━━━━━━━━━━━━━━━━━━━━── | $155,604 | +$12,386 |
| 2026-04-22 | ━━━━━━━━━━━━━━━━━━━━──── | $142,991 | -$12,613 |
| 2026-04-23 | ━━━━━━━━━━━━━━━━━━━━──── | $139,720 | -$3,271 |
| 2026-04-24 | ━━━━━━━━━━━━━━━━━━━━━━━━ | $168,042 | +$28,322 |
| 2026-04-25 | ━━━━━━━━━━━━━━━━━━━━━━━━ | $166,388 | -$1,654 |
| 2026-04-26 | ━━━━━━━━━━━━━━━━━━━━━━━━ | $165,271 | -$1,117 |
ATH $168,042 2026-04-24 · -1.6% from ATH · max drawdown -10.2%
firma show snapshot <ticker>
With a ticker: shows a per-holding time series. Shares, price, market
value, and unrealized P&L on each snapshot date. A drawdown summary
line appears below the table.
$firma show snapshot TSLA
| DATE | SHARES | PRICE | MKT VALUE | UNREALIZED P&L |
|---|---|---|---|---|
| 2026-04-24 | 392.0000 | $350.40 | $137,356.80 | +$40,879.04 |
| 2026-04-25 | 392.0000 | $347.18 | $136,094.56 | +$39,616.80 |
| 2026-04-26 | 392.0000 | $344.97 | $135,228.24 | +$38,750.48 |
ATH $137,356.80 2026-04-24 · -1.6% from ATH · max drawdown -1.6%
Use
--from 2026-01-01 --to 2026-04-26 to limit the date range.
Add --json to get machine-readable output for scripts or Claude.Reading the Drawdown Line
Every
firma show snapshot output appends a one-line drawdown summary
below the data. Here's what each part means:ATHAll-Time High: the highest market value recorded in your snapshot history. Just the peak number in the dataset, nothing more.
-1.6% from ATHHow far below the ATH you are right now, as a percentage. Zero (shown in green as "at all-time high") means today is a new peak. Shown in red when you are in drawdown.
max drawdownThe worst peak-to-trough decline across your entire snapshot history. The biggest percentage drop before a recovery. -10% means at some point the portfolio fell 10% from a local peak before recovering. A number close to 0% means the portfolio has never dropped sharply from a peak.
Drawdown is computed from your recorded snapshots only, not intraday prices.
Run
firma add snapshot daily (or via cron) for a continuous series -
gaps in the history will produce a coarser picture.Edit and Delete
firma edit snapshotInteractive picker: select date → ticker → field to updatefirma delete snapshot [date]Delete all entries for a date. Prompts if date is omittedfirma rm snapshot is an alias for firma delete snapshot.With Claude
Claude Desktop · firma MCP connected
You
How has my portfolio performed over the last week?
Claude
Portfolio rose from $143,218 → $165,271 over 7 days, up +$22,053 (+15.4%). Best day was Apr 24 (+$28,322) on a broad market rally. TSLA up +20.4% across the week.