---
title: Benchmark
description: "Compare your portfolio return against SPY, QQQ, or any custom index over the same period. It's a simple question: are you beating the market, or just riding along with it?"
---

export const optionsRows = [
  { cmd: '--from YYYY-MM-DD',   desc: 'Start date (default: earliest snapshot or transaction)' },
  { cmd: '--to YYYY-MM-DD',     desc: 'End date (default: today)' },
  { cmd: '-b, --benchmarks',    desc: 'Comma-separated tickers (default: SPY,QQQ; try IWM, DIA, or VOO)' },
  { cmd: '--json',              desc: 'Output as JSON for scripting' },
];

export const modes = [
  {
    icon: 'snap',
    title: 'With daily snapshots (preferred)',
    desc: "Uses your day-by-day portfolio total for a true like-for-like comparison against the benchmark's daily close. The more snapshots you have, the more reliable the result.",
  },
  {
    icon: 'cost',
    title: 'Without snapshots (fallback)',
    desc: <>Compares total cost basis to current market value, with a note in the output. It does not account for capital being added on different dates, so treat it as directional only. Run <code>firma add snapshot</code> regularly to upgrade.</>,
  },
];

<Section label="firma show benchmark">
Pulls daily candles for each benchmark from Finnhub and compares total
return over the same window your portfolio covered. When daily snapshots
exist, the start date is your earliest snapshot. Otherwise it falls back
to your earliest transaction date with a cost-basis comparison.

<div className="terminal">
  <div className="terminal-line">
    <span className="term-prompt">$</span>
    <span className="term-cmd">firma show benchmark</span>
  </div>
  <pre className="term-pre"><span className="d">Benchmark Comparison  2024-01-02 → 2026-04-27  (846d)</span></pre>
  <table className="term-table">
    <tbody>
      <tr><td>Portfolio</td><td className="td-green">+61.23%</td><td className="td-muted">$100,000 → $161,230</td><td className="td-muted">(snapshot)</td></tr>
      <tr className="sep"><td colSpan={4}/></tr>
      <tr><td>SPY</td><td className="td-green">+28.41%</td><td className="td-muted">$450.00 → $578.00</td><td/></tr>
      <tr><td>QQQ</td><td className="td-green">+35.10%</td><td className="td-muted">$380.00 → $513.80</td><td/></tr>
      <tr className="sep"><td colSpan={4}/></tr>
      <tr><td>Alpha vs SPY</td><td className="td-green">+32.82%</td><td/><td/></tr>
      <tr><td>Alpha vs QQQ</td><td className="td-green">+26.13%</td><td/><td/></tr>
    </tbody>
  </table>
</div>

  <Note>
    Requires a Finnhub API key. Free plan provides up to 1 year of daily
    candle data. For longer comparisons, the response includes a warning
    and the benchmark window is clipped.
  </Note>
</Section>

<Section label="Options">
  <CommandTable rows={optionsRows} />
</Section>

<Section label="Snapshot vs Cost-basis Mode">
  <FeatureList items={modes} />
</Section>
