---
title: Snapshot
description: Record your portfolio value at a point in time. Snapshots let you track how total market value and individual positions evolve day by day.
---

export const drawdownRows = [
  { cmd: 'ATH',                desc: 'All-Time High: the highest market value recorded in your snapshot history. Just the peak number in the dataset, nothing more.' },
  { cmd: '-1.6% from ATH',     desc: 'How 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.' },
  { cmd: 'max drawdown',       desc: 'The 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.' },
];

export const editDeleteRows = [
  { cmd: <code>firma edit snapshot</code>,          desc: 'Interactive picker: select date → ticker → field to update' },
  { cmd: <code>firma delete snapshot [date]</code>, desc: 'Delete all entries for a date. Prompts if date is omitted' },
];

export const claudeExchange = [{
  user: 'How has my portfolio performed over the last week?',
  ai: <p>
    Portfolio rose from <code>$143,218</code> → <code>$165,271</code> over 7 days,{' '}
    up <code>+$22,053 (+15.4%)</code>. Best day was Apr 24 (<code>+$28,322</code>)
    on a broad market rally. TSLA up <code>+20.4%</code> across the week.
  </p>,
}];

<Section label="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.

  <Terminal
    command="firma add snapshot"
    rows={[
      { type: 'val',  label: '→', value: 'Syncing prices...' },
      { type: 'beat', text: 'Snapshot recorded for 2026-04-26: 4 holdings.' },
    ]}
  />

  <Note>
    Requires a Finnhub API key. Set it once with{' '}
    <code>firma config set finnhub-key &lt;key&gt;</code>.
    Snapshots are stored in <code>~/.firma/firma.db</code> and never overwritten
    for the same date unless you re-run on the same day.
  </Note>
</Section>

<Section label="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 <code>--from</code> and <code>--to</code> to narrow the date range.
Add <code>-c USD</code> to convert amounts to a foreign currency.

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show snapshot</span>
  </div>
  <table className="term-table">
    <thead>
      <tr><th>DATE</th><th colSpan={2}>TOTAL MARKET VALUE</th><th></th></tr>
    </thead>
    <tbody>
      <tr className="sep"><td colSpan={4}/></tr>
      <tr><td className="td-muted">2026-04-20</td><td><span className="term-pre g">{'━'.repeat(20)}</span>{'────'}</td><td>$143,218</td><td/></tr>
      <tr><td className="td-muted">2026-04-21</td><td><span className="term-pre g">{'━'.repeat(22)}</span>{'──'}</td><td>$155,604</td><td className="td-green">+$12,386</td></tr>
      <tr><td className="td-muted">2026-04-22</td><td><span className="term-pre o">{'━'.repeat(20)}</span>{'────'}</td><td>$142,991</td><td className="td-orange">-$12,613</td></tr>
      <tr><td className="td-muted">2026-04-23</td><td><span className="term-pre o">{'━'.repeat(20)}</span>{'────'}</td><td>$139,720</td><td className="td-orange">-$3,271</td></tr>
      <tr><td className="td-muted">2026-04-24</td><td><span className="term-pre g">{'━'.repeat(24)}</span></td><td>$168,042</td><td className="td-green">+$28,322</td></tr>
      <tr><td className="td-muted">2026-04-25</td><td><span className="term-pre o">{'━'.repeat(24)}</span></td><td>$166,388</td><td className="td-orange">-$1,654</td></tr>
      <tr><td className="td-muted">2026-04-26</td><td><span className="term-pre o">{'━'.repeat(24)}</span></td><td>$165,271</td><td className="td-orange">-$1,117</td></tr>
      <tr className="sep"><td colSpan={4}/></tr>
    </tbody>
  </table>
  <pre className="term-pre" style={{ marginTop: '0.5rem' }}>
    <span className="td-muted">ATH  $168,042  2026-04-24  ·  </span>
    <span className="term-pre o">-1.6% from ATH</span>
    <span className="td-muted">  ·  max drawdown  -10.2%</span>
  </pre>
</div>
</Section>

<Section label="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.

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show snapshot TSLA</span>
  </div>
  <table className="term-table">
    <thead>
      <tr><th>DATE</th><th>SHARES</th><th>PRICE</th><th>MKT VALUE</th><th>UNREALIZED P&amp;L</th></tr>
    </thead>
    <tbody>
      <tr className="sep"><td colSpan={5}/></tr>
      <tr><td className="td-muted">2026-04-24</td><td>392.0000</td><td>$350.40</td><td>$137,356.80</td><td className="td-green">+$40,879.04</td></tr>
      <tr><td className="td-muted">2026-04-25</td><td>392.0000</td><td>$347.18</td><td>$136,094.56</td><td className="td-green">+$39,616.80</td></tr>
      <tr><td className="td-muted">2026-04-26</td><td>392.0000</td><td>$344.97</td><td>$135,228.24</td><td className="td-green">+$38,750.48</td></tr>
      <tr className="sep"><td colSpan={5}/></tr>
    </tbody>
  </table>
  <pre className="term-pre" style={{ marginTop: '0.5rem' }}>
    <span className="td-muted">ATH  $137,356.80  2026-04-24  ·  </span>
    <span className="term-pre o">-1.6% from ATH</span>
    <span className="td-muted">  ·  max drawdown  -1.6%</span>
  </pre>
</div>

  <Note>
    Use <code>--from 2026-01-01 --to 2026-04-26</code> to limit the date range.
    Add <code>--json</code> to get machine-readable output for scripts or Claude.
  </Note>
</Section>

<Section label="Reading the Drawdown Line">
Every <code>firma show snapshot</code> output appends a one-line drawdown summary
below the data. Here's what each part means:

  <CommandTable rows={drawdownRows} />

  <Note>
    Drawdown is computed from your recorded snapshots only, not intraday prices.
    Run <code>firma add snapshot</code> daily (or via cron) for a continuous series -
    gaps in the history will produce a coarser picture.
  </Note>
</Section>

<Section label="Edit and Delete">
  <CommandTable rows={editDeleteRows} />

  <Note>
    <code>firma rm snapshot</code> is an alias for <code>firma delete snapshot</code>.
  </Note>
</Section>

<Section label="With Claude">
  <ChatDemo header="Claude Desktop · firma MCP connected" exchanges={claudeExchange} />
</Section>
