gloomberb 0.16.2 → 0.16.4

package/src/cli/commands/market.ts

@@ -7,14 +7,23 @@ import type {
   CorporateActionsData,
   HolderData,
   OptionsChain,
+  Quote,
   TickerFinancials,
 } from "../../types/financials";
 import { currencyMinorDigits, formatMarketPrice, formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-data/market/format";
-import { getActiveQuoteDisplay, marketStateLabel } from "../../market-data/market/status";
-import { formatCompact, formatDistributionAmount, formatPercent } from "../../utils/format";
+import {
+  EXTENDED_SESSION_LABELS,
+  getExtendedSessionDisplay,
+  getQuoteSessionFields,
+  getRegularSessionDisplay,
+  marketStateLabel,
+  type ExtendedSession,
+} from "../../market-data/market/status";
+import { formatCompact, formatDistributionAmount, formatPercent, formatPercentRaw } from "../../utils/format";
 import { withCliServices, withMarketData } from "../context";
-import { isoDate, parsePositiveInt, requireArg, takeFlag, takeOption } from "./command-utils";
-import { CLI_COMMAND_GROUPS } from "../help";
+import { isoDate, parsePositiveInt, rejectExtraArgs, requireOneArg, takeFlag, takeOption } from "./command-utils";
+import type { BuiltinCliCommandDef } from "../command-options";
+import { CLI_COMMAND_GROUPS, TABLE_SECTION_OPTION } from "../help";
 import {
   formatChangePercentCell,
   formatCountCell,
@@ -31,22 +40,59 @@ import {
   recommendationTotal,
   targetUpside,
 } from "../../plugins/builtin/research/analyst-model";
-import { optionQuoteSide } from "../../plugins/builtin/options/market-reference";
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
-import { renderFundamentalsReport } from "./ticker";
-import { historyPriceDecimals, historyRows } from "../history-rows";
+import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
+import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../market-data/options-alternatives";
+import { fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+import {
+  chainHasExpiry,
+  chainWithModelFigures,
+  formatExpiryList,
+  loadOptionModelInputs,
+  formatOptionDeltaCell,
+  formatOptionIvCell,
+  formatOptionQuoteCell,
+  missingExpiryMessage,
+  OPTION_MODEL_RATE,
+  OPTIONS_USAGE,
+  optionRows,
+  parseOptionExpiration,
+} from "./options-chain";
+import { DEFAULT_LEAPS_CRITERIA, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions } from "./options-leaps";
+import type { CliResultColumn } from "../result";
+import {
+  exportRowsTable,
+  reportFooterLines,
+  selectReportTables,
+  type CliReportTables,
+} from "../report-tables";
+import {
+  historyFacts,
+  historyFlagNote,
+  historyAllRangeYears,
+  historyIntervalsByRange,
+  historyNotes,
+  historyPriceDecimals,
+  historyRows,
+  historyUnit,
+} from "../history-rows";
 import { CRYPTO_BOARD_HINT, quoteNotes } from "./crypto-hints";
 import { formatUtcTime } from "../../utils/utc-time";
+import { isFiniteNumber } from "../../utils/guards";
 import { exportedFundamentals } from "../../utils/price-earnings";
 import { fundamentalsFreshness, quotesFreshness, rowsFreshness } from "../freshness";
 import {
   barHistoryFreshness,
   barResolutionFromDates,
+  cloudNewsFreshness,
+  cloudRealtimeAccess,
   REPORTED_DATA,
   SEC_FILINGS,
 } from "../../plugins/builtin/shared/report-freshness";
 import {
+  bareListingNote,
   EXCHANGE_OPTION,
+  isNoProviderError,
   listingHeading,
   listingIdentity,
   listingTitle,
@@ -54,22 +100,32 @@ import {
   loadForListing,
   loadListingQuote,
   notTradedMessage,
+  quoteBareListing,
   requireCliListing,
   type CliListing,
+  type ListingDataRequest,
   type ListingIdentity,
 } from "../listing-arg";
+import { indexRootAlsoLine, indexRootFor, indexRootTryLine } from "../index-roots";
+import { providerMissReason } from "../../sources/provider-errors";
+import { isNotATickerMessage } from "../not-a-ticker";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
 import { isUsListingExchange } from "../../utils/exchanges";
 import { nonUsSecListingVenue } from "../../utils/sec";
 import type { MarketContext } from "../types";
+import { windowRows } from "../row-window";
+import { crossRate, describeFxRate, isUsableRate, parseFxRequest } from "../fx-pair";
 import {
   holderListFacts,
+  holderShareBasisMarker,
+  holderShareBasisNote,
   holderValueBasis,
   moneyColumnHeader,
   nonUsHolderCaveat,
   sharedReportDate,
 } from "../../plugins/builtin/holders/report-header";
+import { formatHolderOwnershipPercent, holderValueCurrency } from "../../plugins/builtin/holders/format";
 import { fetchBeneficialOwners } from "../../plugins/builtin/holders/beneficial-client";
 import { filingFormMatches, SEC_FILING_FETCH_LIMIT } from "../../plugins/builtin/sec/forms";
 import {
@@ -117,28 +173,67 @@ function listingMetadata(identity: ListingIdentity) {
   return { symbol: identity.symbol, exchange: identity.exchange || null, name: identity.name };
 }
 
+// Fitted to a narrow width, the columns marked optional go first (higher dropPriority first), then Name is cut short.
+// What a user types or reads the price by stays whole.
 const QUOTE_LEAD_COLUMNS = [
-  { key: "symbol", header: "Symbol" },
+  { key: "symbol", header: "Symbol", shrink: false },
   { key: "name", header: "Name" },
   {
     key: "price",
     header: "Last",
     align: "right" as const,
-    format: (value: unknown, row: ReturnType<typeof quoteRows>[number]) => (
-      row.error && !value ? cliStyles.danger("unavailable") : String(value ?? "")
+    format: (value: unknown, row: QuoteRow) => (
+      row.error && !value
+        // A typo is not an outage: say what is wrong with the symbol itself.
+        ? isNotATickerMessage(row.error) ? cliStyles.warning("not a ticker") : cliStyles.danger("unavailable")
+        : String(value ?? "")
     ),
   },
   { key: "changePercent", header: "Chg%", align: "right" as const, format: formatChangePercentCell },
-  { key: "session", header: "Session" },
+  // Text drops a column no row fills, so a table without an extended print stays as narrow as before.
+  extendedColumn("PRE"),
+  extendedColumn("POST"),
+  { key: "session", header: "Session", shrink: false },
 ];
 
+type QuoteRow = ReturnType<typeof quoteRows>[number];
+
+/** The pre-market or after-hours print and its move from the regular close, in its own column. */
+function extendedColumn(session: ExtendedSession) {
+  return {
+    key: session === "PRE" ? "preMarket" : "afterHours",
+    header: EXTENDED_SESSION_LABELS[session],
+    align: "right" as const,
+    value: (row: QuoteRow) => row.extendedSession === session && row.extendedPrice
+      ? [row.extendedPrice, row.extendedChangePercent == null ? "" : formatPercentRaw(row.extendedChangePercent)].join(" ").trim()
+      : "",
+    format: (value: unknown, row: QuoteRow) => (
+      value ? [row.extendedPrice, formatChangePercentCell(row.extendedChangePercent)].join(" ").trim() : ""
+    ),
+  };
+}
+
+/** A percent to two decimals, as the table prints it. */
+function roundedPercent(value: number | undefined): number | null {
+  return value == null ? null : Number(value.toFixed(2));
+}
+
 function quoteColumns() {
   return [
     ...QUOTE_LEAD_COLUMNS,
-    { key: "currency", header: "Cur" },
-    // Whether the price is real-time or delayed: a feed state, not where it came from.
-    { key: "source", header: "Feed", format: (value: unknown) => value === "live" || value === "delayed" ? value : "" },
-    { key: "updatedAt", header: "Updated" },
+    { key: "currency", header: "Cur", shrink: false, optional: true, dropPriority: 1 },
+    // Whether the price is real-time, delayed or stale: a feed state, not where it came from. A stale
+    // row says so here, so the closing line's "N of M stale" always points at rows the table marks.
+    {
+      key: "feed",
+      header: "Feed",
+      shrink: false,
+      optional: true,
+      dropPriority: 2,
+      format: (value: unknown) => value === "stale" ? cliStyles.warning(value) : String(value ?? ""),
+    },
+    // In a narrow terminal the closing line's as-of stands in for each row's.
+    { key: "updatedAt", header: "Updated", shrink: false, optional: true, dropPriority: 3 },
   ];
 }
 
@@ -146,9 +241,10 @@ function compareColumns() {
   return [
     ...QUOTE_LEAD_COLUMNS,
     { key: "previousClose", header: "Prev Close", align: "right" as const },
-    { key: "dayRange", header: "Day Range", align: "right" as const },
-    { key: "volume", header: "Volume", align: "right" as const, format: formatCountCell },
-    { key: "currency", header: "Cur" },
+    // A narrow terminal drops these before it cuts the names short.
+    { key: "dayRange", header: "Day Range", align: "right" as const, optional: true, dropPriority: 1 },
+    { key: "volume", header: "Volume", align: "right" as const, format: formatCountCell, optional: true, dropPriority: 2 },
+    { key: "currency", header: "Cur", shrink: false, optional: true, dropPriority: 3 },
   ];
 }
 
@@ -157,11 +253,20 @@ function errorMessage(error: unknown): string | null {
   return error instanceof Error ? error.message : String(error);
 }
 
-function quoteRows(results: QuoteCliRecord[]) {
+/** What the Feed cell says: stale wins over the feed's own live or delayed, as the closing line counts it. */
+function quoteFeedState(quote: QuoteCliRecord["quote"], now: number): "stale" | "live" | "delayed" | "" {
+  if (!quote) return "";
+  if (isQuoteStaleForCurrentSession(quote, now)) return "stale";
+  return quote.dataSource === "live" || quote.dataSource === "delayed" ? quote.dataSource : "";
+}
+
+function quoteRows(results: QuoteCliRecord[], now = Date.now()) {
   return results.map((result) => {
     const quote = result.quote;
-    // Same price and move as the quote monitor: the live session's print against the daily reference.
-    const display = getActiveQuoteDisplay(quote);
+    // Last and Chg% are the regular session, as `ticker` and the quote monitor read it; a
+    // pre-market or after-hours print is its own column, measured from that session's close.
+    const display = getRegularSessionDisplay(quote);
+    const extended = getExtendedSessionDisplay(quote);
     // An index level is in points, not in the currency its members trade in.
     const indexPoints = quote?.instrumentType?.trim().toUpperCase() === "INDEX";
     // Pad to two decimals so a column lines up, but never past the currency's minor unit (JPY has none).
@@ -183,9 +288,14 @@ function quoteRows(results: QuoteCliRecord[]) {
       priceBasis: quote?.priceBasis ?? null,
       instrumentType: quote?.instrumentType ?? null,
       change: display?.change ?? null,
-      changePercent: display?.changePercent == null ? null : Number(display.changePercent.toFixed(2)),
+      changePercent: roundedPercent(display?.changePercent),
+      extendedSession: extended?.session ?? null,
+      extendedPrice: price(extended?.price),
+      rawExtendedPrice: extended?.price ?? null,
+      extendedChange: extended?.change ?? null,
+      extendedChangePercent: roundedPercent(extended?.changePercent),
       session: quote?.marketState ? marketStateLabel(quote.marketState) : "",
-      // The close the shown move is measured from; a pre-market move starts at the last close.
+      // The close the shown move is measured from: the one before the session Last is.
       previousClose: price(display?.change != null ? display.price - display.change : quote?.previousClose),
       dayRange: quote?.low != null && quote.high != null
         ? indexPoints ? `${price(quote.low)}-${price(quote.high)}` : formatPriceRange(quote.low, quote.high, quote.currency, options, "-")
@@ -194,6 +304,7 @@ function quoteRows(results: QuoteCliRecord[]) {
       currency: quote?.currency ?? "",
       providerId: quote?.providerId ?? "",
       source: quote?.dataSource ?? quote?.providerId ?? "",
+      feed: quoteFeedState(quote, now),
       updatedAt: quote?.lastUpdated ? new Date(quote.lastUpdated).toISOString() : "",
       error: result.error ?? "",
     };
@@ -250,6 +361,7 @@ function holderRows(data: HolderData, ownerTypes?: Set<string>) {
     value: holder.value ?? null,
     percentHeld: holder.percentHeld ?? null,
     changeShares: holder.changeShares ?? null,
+    shareBasis: holder.shareBasis ?? null,
   }));
 }
 
@@ -323,22 +435,6 @@ function corporateActionRows(data: CorporateActionsData) {
   ].sort((left, right) => right.date.localeCompare(left.date));
 }
 
-function optionRows(chain: OptionsChain) {
-  return [...chain.calls.map((contract) => ({ side: "call", ...contract })), ...chain.puts.map((contract) => ({ side: "put", ...contract }))]
-    .map((contract) => ({
-      side: contract.side,
-      contract: contract.contractSymbol,
-      strike: contract.strike,
-      last: contract.lastPrice,
-      bid: contract.bid,
-      ask: contract.ask,
-      volume: contract.volume,
-      openInterest: contract.openInterest,
-      iv: contract.impliedVolatility,
-      expiration: new Date(contract.expiration * 1000).toISOString().slice(0, 10),
-    }));
-}
-
 /**
  * After a US open, a chain whose latest trade predates it still carries the
  * prior session's quotes and volume. The delayed feed lags the open by about
@@ -353,11 +449,6 @@ function priorSessionChainWarning(chain: OptionsChain, exchange: string, now: nu
   return `No option trades this session yet (last trade ${chain.asOf})`;
 }
 
-function formatOptionQuoteCell(row: Record<string, unknown>, side: "bid" | "ask"): string {
-  const quote = optionQuoteSide({ bid: Number(row.bid), ask: Number(row.ask) }, side);
-  return quote == null ? "—" : String(quote);
-}
-
 /** Per-share earnings to the cent, as reported; consensus averages carry more digits. */
 function formatEpsCell(value: unknown): string {
   return typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "";
@@ -390,20 +481,25 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
     const targets: QuoteSubscriptionTarget[] = listings.map((listing) => ({ symbol: listing.request.symbol, exchange: listing.request.exchange }));
     const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh });
     const listingOf = (result: QuoteBatchResult, index: number) => listings[targets.indexOf(result.target)] ?? listings[index]!;
-    // A listing with no quote on an exchange its symbol is not listed on says so; venues are only looked up for those.
-    const notTraded = await Promise.all(results.map((result, index) => (
-      result.quote ? null : notTradedMessage(listingOf(result, index), market)
-    )));
-    if (listings.length === 1 && notTraded[0]) ctx.fail(notTraded[0]);
+    const request = { command: commandName, noun: "quote" };
+    const answers = await Promise.all(results.map((result, index) => answerQuote(result, listingOf(result, index), market, request, ctx.cliOptions.refresh)));
+    const failed = answers[0]?.failure;
+    if (listings.length === 1 && failed) ctx.fail(failed.message, failed.details);
     // Each row names its listing by key (SAN:EPA) and company, so the table needs no line above it.
-    const data = results.map((result, index) => ({
+    const data = answers.map(({ result, listing, failure }) => ({
       target: result.target,
-      listing: listingMetadata(listingIdentity(listingOf(result, index), result.quote)),
+      listing: listingMetadata(listingIdentity(listing, result.quote)),
+      // The figures the table shows, beside the quote as the source sent it.
+      ...getQuoteSessionFields(result.quote),
       quote: result.quote,
-      error: notTraded[index] ?? errorMessage(result.error),
+      error: failure?.oneLine ?? errorMessage(result.error),
     }));
-    // Text mode shows only "unavailable" in the cell; the JSON rows already carry each reason.
-    const notes = ctx.cliOptions.format === "text" ? quoteNotes(data, { exchange }) : [];
+    const notes = [
+      // Which listing a bare symbol was read as, and the index a bare root is not, are in no row.
+      ...answers.flatMap((answer) => answer.notes),
+      // Text mode shows only "unavailable" in the cell; the JSON rows already carry each reason.
+      ...ctx.cliOptions.format === "text" ? quoteNotes(data, { exchange }) : [],
+    ];
     ctx.printResult({
       data,
       warnings: notes.length > 0 ? notes : undefined,
@@ -415,17 +511,74 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
   });
 }
 
+interface QuoteAnswer {
+  result: QuoteBatchResult;
+  /** The listing the row is: the one asked for, or the venue a bare symbol was quoted on. */
+  listing: CliListing;
+  /** Why there is no quote, when there is more to say than the source's own error. */
+  failure?: { message: string; details?: string; oneLine: string };
+  notes: string[];
+}
+
+/**
+ * One symbol's row of `quote` and `compare`. A listing on an exchange its symbol
+ * is not listed on says so. A bare symbol the data service read on its home
+ * listing abroad names that venue (SXR8 -> XETRA). One no source quotes is
+ * quoted on its listings (`quoteBareListing`), else names them; a bare index
+ * root (VIX) also names its index (^VIX). Venues are only looked up for a
+ * symbol with no quote, so a request that succeeds costs no search.
+ */
+async function answerQuote(
+  result: QuoteBatchResult,
+  listing: CliListing,
+  market: MarketContext,
+  request: ListingDataRequest,
+  refresh: boolean,
+): Promise<QuoteAnswer> {
+  const root = listing.exchange ? null : indexRootFor(listing.symbol);
+  // A bare root that quoted something else, such as MOVE (Corvex), points at the index too.
+  const also = (quote: Quote) => root && quote.instrumentType?.trim().toUpperCase() !== "INDEX"
+    ? [indexRootAlsoLine(root, request.command)] : [];
+  if (result.quote) return { result, listing, notes: [bareListingNote(listing, result.quote) ?? [], also(result.quote)].flat() };
+  const notTraded = await notTradedMessage(listing, market);
+  if (notTraded) return { result, listing, failure: { message: notTraded, oneLine: notTraded }, notes: [] };
+  if (!isNoProviderError(result.error)) return { result, listing, notes: [] };
+  const other = await quoteBareListing(listing, market, request, { refresh });
+  if (other?.kind === "quoted") {
+    return {
+      result: { target: other.listing.request, quote: other.quote },
+      listing: other.listing,
+      notes: [other.note, ...also(other.quote)],
+    };
+  }
+  const indexLine = root ? indexRootTryLine(root, request.command) : null;
+  if (!other && !indexLine) return { result, listing, notes: [] };
+  const message = other?.message ?? `${listing.symbol} has no ${request.noun}.`;
+  const details = [other?.details, indexLine].filter(Boolean).join("\n");
+  const oneLine = [
+    message,
+    other ? `Other listings: ${other.others.join(", ")}.` : "",
+    indexLine ?? "",
+  ].filter(Boolean).join(" ");
+  return { result, listing, failure: { message, details, oneLine }, notes: [] };
+}
+
 /** A crypto pair that will not load points at the crypto board. Structured formats keep the error as thrown. */
 function failHistory(error: unknown, symbol: string, ctx: Parameters<CliCommandDef["execute"]>[1]): never {
   if (ctx.cliOptions.format !== "text" || !isCryptoPairSymbol(symbol)) throw error;
   return ctx.fail(errorMessage(error) ?? `No history available for ${symbol}`, CRYPTO_BOARD_HINT);
 }
 
+const HISTORY_USAGE = "history <symbol> [--range <range>]";
+const HISTORY_ALL_RANGE = `ALL gives the full history the source has, up to ${historyAllRangeYears()} years`;
+/** Options people reach for to ask for dates, which history answers with a range. */
+const DATE_WINDOW_OPTIONS = new Set(["--from", "--to", "--start", "--end", "--since", "--until", "--date", "--start-date", "--end-date"]);
+
 async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const range = parseRange(takeOption(args, "--range"), ctx);
   const requestedExchange = takeOption(args, "--exchange");
-  const raw = requireArg(args[0], "Usage: gloomberb history <symbol> [--range <range>]", ctx);
+  const raw = requireOneArg(args, HISTORY_USAGE, "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, requestedExchange, market, ctx);
     const { symbol, exchange } = listing.request;
@@ -434,12 +587,18 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       ? market.dataProvider.getPriceHistoryWithMetadata(symbol, exchange, range, context)
       : market.dataProvider.getPriceHistory(symbol, exchange, range, context).then((points) => ({ points, resolution: null }));
     const [{ points, resolution }, quote] = await Promise.all([
-      loadForListing(listing, market, ctx, load, (loaded) => loaded.points.length === 0)
+      loadForListing(listing, market, ctx, load, (loaded) => loaded.points.length === 0, {
+        command: range === "1Y" ? "history" : `history --range ${range}`, noun: "history",
+      })
         .catch((error) => failHistory(error, listing.key, ctx)),
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
-    const data = historyRows(points, resolution);
+    // Without a quote currency, the listing metadata research reads (as `ticker` does) may still state it.
+    const listed = quote?.currency ? quote : await market.dataProvider.getQuoteMetadata?.(symbol, exchange).catch(() => null);
+    const unit = historyUnit(listing.symbol, listed ?? quote);
+    const data = historyRows(points, resolution, unit.currency);
+    const interval = data[0]?.interval ?? null;
     const decimals = historyPriceDecimals(data, listing.saved?.metadata.assetCategory);
     const price = (value: unknown) => typeof value === "number" ? value.toFixed(decimals) : "";
     // Intraday bars print in UTC, as the charts and time and sales label them, not the host zone.
@@ -450,17 +609,48 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       observedKey: "date",
       oldest: null,
     });
-    ctx.printResult({ data, metadata: { ...listingMetadata(identity), range, resolution }, freshness }, {
-      heading: listingHeading(identity),
+    const notes = [...historyNotes(range, interval, data[0]?.date), historyFlagNote(data) ?? []].flat();
+    const priceColumns: CliResultColumn[] = [
+      intraday
+        ? { key: "date", header: "Time", format: (value) => typeof value === "string" ? formatUtcTime(value) : "" }
+        : { key: "date", header: "Date" },
+      { key: "open", header: "Open", align: "right", format: price },
+      { key: "high", header: "High", align: "right", format: price },
+      { key: "low", header: "Low", align: "right", format: price },
+      { key: "close", header: "Close", align: "right", format: price },
+      { key: "volume", header: "Volume", align: "right", format: formatCountCell },
+    ];
+    // Text shows a flag only on a bar that has one; the column is dropped when none does.
+    const flagColumn: CliResultColumn = {
+      key: "flag", header: "Flag", format: (value) => typeof value === "string" ? cliStyles.warning(value) : "",
+    };
+    ctx.printResult({
+      data,
+      metadata: {
+        ...listingMetadata(identity),
+        range,
+        resolution,
+        requestedRange: range,
+        currency: unit.currency,
+        unit: unit.unit,
+        interval,
+        firstDate: data[0]?.date ?? null,
+        lastDate: data.at(-1)?.date ?? null,
+        bars: data.length,
+        asOf: freshness?.asOf ?? null,
+      },
+      ...(notes.length > 0 ? { warnings: notes } : {}),
+      freshness,
+    }, {
+      heading: `${listingHeading(identity)}\n${cliStyles.muted(historyFacts(unit, data).join("  ·  "))}`,
+      dateKey: "date",
+      textColumns: [...priceColumns, flagColumn],
+      // Every exported row says its currency and bar size, so it survives head and concatenation.
       columns: [
-        intraday
-          ? { key: "date", header: "Time", format: (value) => typeof value === "string" ? formatUtcTime(value) : "" }
-          : { key: "date", header: "Date" },
-        { key: "open", header: "Open", align: "right", format: price },
-        { key: "high", header: "High", align: "right", format: price },
-        { key: "low", header: "Low", align: "right", format: price },
-        { key: "close", header: "Close", align: "right", format: price },
-        { key: "volume", header: "Volume", align: "right", format: formatCountCell },
+        ...priceColumns,
+        { key: "currency", header: "Currency" },
+        { key: "interval", header: "Interval" },
+        flagColumn,
       ],
     });
   });
@@ -468,16 +658,38 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
 
 type FinancialsView = "statements" | "fundamentals" | "valuation";
 
+const STATEMENT_COLUMNS: CliResultColumn<ReturnType<typeof financialStatementRows>[number]>[] = [
+  { key: "date", header: "Date" },
+  { key: "revenue", header: "Revenue", align: "right", format: (value) => value == null ? "" : formatCompact(Number(value)) },
+  { key: "grossProfit", header: "Gross", align: "right", format: (value) => value == null ? "" : formatCompact(Number(value)) },
+  { key: "operatingIncome", header: "Op Inc", align: "right", format: (value) => value == null ? "" : formatCompact(Number(value)) },
+  { key: "netIncome", header: "Net Inc", align: "right", format: (value) => value == null ? "" : formatCompact(Number(value)) },
+  { key: "eps", header: "EPS", align: "right", format: (value) => value == null ? "" : formatPerShareNumber(Number(value)) },
+  { key: "currency", header: "Cur" },
+];
+
 async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1], view: FinancialsView) {
   const args = [...rawArgs];
   const exchangeOption = takeOption(args, "--exchange");
+  const sectionFlag = args.some((arg) => arg === "--section" || arg.startsWith("--section="));
+  const section = takeOption(args, "--section");
   const commandName = view === "statements" ? "financials" : view;
-  const raw = requireArg(args[0], `Usage: gloomberb ${commandName} <symbol>`, ctx);
+  const tabular = ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson";
+  if (sectionFlag && !tabular) ctx.fail("--section picks one table of --csv or --ndjson output.");
+  if (sectionFlag && !section?.trim()) ctx.fail("--section needs a section title or number.");
+  const raw = requireOneArg(args, `${commandName} <symbol>`, "symbol", ctx);
+  const selectTables = (tables: CliReportTables) => {
+    try {
+      return selectReportTables(tables, section);
+    } catch (error) {
+      return ctx.fail(error instanceof Error ? error.message : String(error));
+    }
+  };
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const financials = await loadForListing(listing, market, ctx, () => market.dataProvider.getTickerFinancials(
       listing.request.symbol, listing.request.exchange, { cacheMode: ctx.cliOptions.refresh ? "refresh" : "default" },
-    ));
+    ), undefined, { command: commandName, noun: commandName === "valuation" ? "valuation data" : commandName });
     const identity = listingIdentity(listing, financials.quote);
     const data: FinancialsCliData = {
       symbol: listing.key,
@@ -486,13 +698,28 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       ...financials,
     };
     if (view !== "statements") {
+      const freshness = fundamentalsFreshness(financials);
       ctx.printResult({
         // JSON reads a multiple over a loss as null with its reason, never as a number.
         data: { ...data, fundamentals: exportedFundamentals(data.fundamentals) },
-        freshness: fundamentalsFreshness(financials),
-      }, { text: () => renderFundamentalsReport(data, view) });
+        freshness,
+      }, {
+        text: () => renderFundamentalsReport(data, view),
+        ...(tabular ? { tables: selectTables(fundamentalsReportTables(data, view, freshness)) } : {}),
+      });
       return;
     }
+    const rows = financialStatementRows(data);
+    const freshness = rowsFreshness(rows, {
+      ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null,
+    });
+    // NDJSON keeps the raw statement rows it always wrote; CSV gets the table and its closing lines.
+    const tables = tabular
+      ? selectTables({
+        tables: [exportRowsTable("Annual statements", STATEMENT_COLUMNS, rows)],
+        footer: reportFooterLines({ freshness }),
+      })
+      : undefined;
     ctx.printResult({
       data,
       metadata: {
@@ -503,21 +730,12 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         fundamentals: exportedFundamentals(financials.fundamentals),
         profile: financials.profile,
       },
-      freshness: rowsFreshness(financialStatementRows(data), {
-        ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null,
-      }),
+      freshness,
     }, {
       heading: listingHeading(identity),
-      rows: financialStatementRows,
-      columns: [
-        { key: "date", header: "Date" },
-        { key: "revenue", header: "Revenue", align: "right", value: (row) => row.revenue == null ? "" : formatCompact(Number(row.revenue)) },
-        { key: "grossProfit", header: "Gross", align: "right", value: (row) => row.grossProfit == null ? "" : formatCompact(Number(row.grossProfit)) },
-        { key: "operatingIncome", header: "Op Inc", align: "right", value: (row) => row.operatingIncome == null ? "" : formatCompact(Number(row.operatingIncome)) },
-        { key: "netIncome", header: "Net Inc", align: "right", value: (row) => row.netIncome == null ? "" : formatCompact(Number(row.netIncome)) },
-        { key: "eps", header: "EPS", align: "right", format: (value) => value == null ? "" : formatPerShareNumber(Number(value)) },
-        { key: "currency", header: "Cur" },
-      ],
+      rows: () => rows,
+      columns: STATEMENT_COLUMNS,
+      ...(tables && ctx.cliOptions.format === "csv" ? { tables } : {}),
     });
   });
 }
@@ -527,9 +745,11 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   const feed = parseNewsFeed(takeOption(args, "--feed"));
   const exchangeOption = takeOption(args, "--exchange");
   if (exchangeOption && !args[0]) ctx.fail("--exchange needs a symbol: gloomberb news <symbol> --exchange <code>");
+  rejectExtraArgs(args, 1, { usage: "news [symbol] [--feed <feed>]", takes: "one symbol at most", advice: "Run it once per symbol." }, ctx);
   await withMarketData(ctx, async (market) => {
     const listing = args[0] ? await requireCliListing(args[0], exchangeOption, market, ctx) : null;
-    const limit = ctx.cliOptions.limit ?? 20;
+    // Stories come newest first, so the newest n are the first n either way.
+    const limit = ctx.cliOptions.tail ?? ctx.cliOptions.limit ?? 20;
     const loadNews = () => market.dataProvider.getNews({
       feed: feed ?? (listing ? "ticker" : "latest"),
       // Still set for news plugins that read the deprecated scope.
@@ -546,9 +766,7 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     ctx.printResult({
       data: articles,
       metadata: { ticker: listing?.key ?? null, ...(identity ? listingMetadata(identity) : {}), feed: feed ?? null },
-      freshness: rowsFreshness(newsRows(articles), {
-        status: "not-a-feed", basis: "published stories", observedKey: "publishedAt", oldest: null,
-      }),
+      freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
     }, {
       ...(identity ? { heading: listingHeading(identity) } : {}),
       rows: newsRows,
@@ -584,10 +802,11 @@ async function registrantUsExchange(market: MarketContext, symbol: string, regis
 
 async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
-  const count = parsePositiveInt(takeOption(args, "--count"), ctx.cliOptions.limit ?? 15, "Count", ctx);
+  // Filings come newest first, so --tail asks for the same first n as --limit.
+  const count = parsePositiveInt(takeOption(args, "--count"), ctx.cliOptions.tail ?? ctx.cliOptions.limit ?? 15, "Count", ctx);
   const exchangeOption = takeOption(args, "--exchange");
   const form = takeOption(args, "--form")?.trim() || null;
-  const raw = requireArg(args[0], "Usage: gloomberb filings <symbol>", ctx);
+  const raw = requireOneArg(args, "filings <symbol> [--count <n>] [--form <form>]", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const { symbol, exchange } = listing.request;
@@ -655,10 +874,14 @@ async function printBeneficialOwners(
   ctx: Parameters<CliCommandDef["execute"]>[1],
 ) {
   const { symbol, exchange } = listing.request;
+  // A listing outside the US sends its company to the lookup, which needs its quote first.
+  const quotePromise = loadListingQuote(market.dataProvider, listing);
+  const abroad = nonUsSecListingVenue(symbol, exchange) ? listingIdentity(listing, await quotePromise) : null;
+  const request = { form: beneficialRouteForm(form), history, listing: { exchange, name: abroad?.name ?? undefined } };
   const [payload, holders, quote] = await Promise.all([
-    loadForListing(listing, market, ctx, () => fetchBeneficialOwners(symbol, { form: beneficialRouteForm(form), history })),
+    loadForListing(listing, market, ctx, () => fetchBeneficialOwners(symbol, request)),
     market.dataProvider.getHolders?.(symbol, exchange).catch(() => null) ?? null,
-    loadListingQuote(market.dataProvider, listing),
+    quotePromise,
   ]);
   const identity = listingIdentity(listing, quote);
   const rows = buildBeneficialReportRows(payload, { history, holders });
@@ -702,7 +925,7 @@ async function runHolders(
   const exchangeOption = takeOption(args, "--exchange");
   const formOption = commandName === "holders" ? takeOption(args, "--form") : undefined;
   const history = commandName === "holders" && takeFlag(args, "--history");
-  const raw = requireArg(args[0], `Usage: gloomberb ${commandName} <symbol>`, ctx);
+  const raw = requireOneArg(args, `${commandName} <symbol>`, "symbol", ctx);
   const form = formOption == null ? "13f" : parseHolderForm(formOption);
   if (!form) ctx.fail(`Unknown form "${formOption}".`, `Use one of ${HOLDER_FORMS.join(", ")}.`);
   if (form === "13f" && history) ctx.fail("--history lists 13D/13G reports.", "Add --form 13d, 13g or all.");
@@ -714,26 +937,33 @@ async function runHolders(
         listing, market, ctx,
         () => market.dataProvider.getHolders(listing.request.symbol, listing.request.exchange),
         (found) => found.holders.length === 0,
+        { command: commandName, noun: "holder data" },
       ),
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
     const rows = holderRows(data, ownerTypes);
-    const limit = ctx.cliOptions.limit;
-    const shown = limit == null ? rows.length : Math.min(limit, rows.length);
+    const shown = windowRows(rows, ctx.cliOptions).rows.length;
     const institutional = !ownerTypes?.has("insider");
     const total = institutional ? data.summary?.institutionsCount ?? null : null;
     const reportDate = sharedReportDate(rows);
-    const valueBasis = rows.length > 0 ? holderValueBasis(reportDate) : null;
+    // A London line's values can be dollars from the 13F filings; the listing's currency is not their unit.
+    const valueCurrency = holderValueCurrency(data);
+    const valueBasis = rows.length > 0 ? holderValueBasis(reportDate, data.valueBasis, valueCurrency) : null;
     const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(identity.exchange || data.exchange, data.currency) : null;
+    const shareBasisNote = holderShareBasisNote(data, rows);
+    const markedRows = rows.some((row) => holderShareBasisMarker(row));
     // The heading names the listing; its unit, date and how much of the list follows on the same line.
-    const facts = holderListFacts({ currency: data.currency, asOf: data.asOf, shown, reported: rows.length, total });
+    const facts = holderListFacts({
+      currency: valueCurrency, listingCurrency: data.currency, asOf: data.asOf, shown, reported: rows.length, total,
+    });
     ctx.printResult({
       data,
       metadata: {
         ...listingMetadata(identity),
         summary: data.summary,
         currency: data.currency ?? null,
+        valueCurrency: valueCurrency ?? null,
         asOf: data.asOf ?? null,
         shown,
         reported: rows.length,
@@ -750,16 +980,23 @@ async function runHolders(
         { key: "name", header: "Holder" },
         { key: "reportDate", header: "Date" },
         { key: "shares", header: "Shares", align: "right", format: formatCountCell },
+        // Marks the rows of a home line held as receipts; absent when no row is.
+        ...(markedRows ? [{ key: "shareBasis", header: "Basis", value: (row: Record<string, unknown>) => holderShareBasisMarker(row) }] : []),
         {
           key: "value",
-          header: moneyColumnHeader("Value", data.currency),
+          header: moneyColumnHeader("Value", valueCurrency),
           align: "right",
           value: (row) => row.value == null ? "" : formatCompact(Number(row.value)),
         },
-        { key: "percentHeld", header: "% Held", align: "right", format: formatFractionPercentCell },
+        {
+          key: "percentHeld",
+          header: "% Held",
+          align: "right",
+          format: (value) => isFiniteNumber(value) ? formatHolderOwnershipPercent(value) : "",
+        },
       ],
       summary: (holderData: HolderData) => [
-        [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? ""].filter(Boolean).join(" "),
+        [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? "", shareBasisNote ?? ""].filter(Boolean).join(" "),
         commandName === "insider" && ownerTypes ? insiderSummary(holderData, ownerTypes) : "",
       ].filter(Boolean).join("\n"),
       empty: `No holders reported for ${listingTitle(identity)}.`,
@@ -770,11 +1007,14 @@ async function runHolders(
 async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const exchangeOption = takeOption(args, "--exchange");
-  const raw = requireArg(args[0], "Usage: gloomberb analyst <symbol>", ctx);
+  const raw = requireOneArg(args, "analyst <symbol>", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const [data, quote] = await Promise.all([
-      loadForListing(listing, market, ctx, () => market.dataProvider.getAnalystResearch(listing.request.symbol, listing.request.exchange)),
+      loadForListing(
+        listing, market, ctx, () => market.dataProvider.getAnalystResearch(listing.request.symbol, listing.request.exchange),
+        undefined, { command: "analyst", noun: "analyst research" },
+      ),
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
@@ -807,11 +1047,14 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
 async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const exchangeOption = takeOption(args, "--exchange");
-  const raw = requireArg(args[0], "Usage: gloomberb events <symbol>", ctx);
+  const raw = requireOneArg(args, "events <symbol>", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const [data, quote] = await Promise.all([
-      loadForListing(listing, market, ctx, () => market.dataProvider.getCorporateActions(listing.request.symbol, listing.request.exchange)),
+      loadForListing(
+        listing, market, ctx, () => market.dataProvider.getCorporateActions(listing.request.symbol, listing.request.exchange),
+        undefined, { command: "events", noun: "corporate events" },
+      ),
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
@@ -835,83 +1078,168 @@ async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execu
 
 async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
+  const leapsOptions = takeLeapsOptions(args);
   const expiration = takeOption(args, "--expiration");
   const exchangeOption = takeOption(args, "--exchange");
-  const raw = requireArg(args[0], "Usage: gloomberb options <symbol> [--expiration <unix>]", ctx);
+  if (leapsOptions.leaps) {
+    if (expiration != null || rawArgs.includes("--expiration")) {
+      ctx.fail("--leaps reads every expiry more than a year out; drop --expiration.", `Usage: gloomberb ${LEAPS_USAGE}`);
+    }
+    const criteria = parseLeapsCriteria(leapsOptions.raw);
+    if ("error" in criteria) ctx.fail(criteria.error, `Usage: gloomberb ${LEAPS_USAGE}`);
+    const symbols = normalizeSymbols(args);
+    if (symbols.length === 0) ctx.fail("--leaps needs at least one symbol.", `Usage: gloomberb ${LEAPS_USAGE}`);
+    await withMarketData(ctx, (market) => runLeapsScreen(symbols, exchangeOption, criteria, market, ctx));
+    return;
+  }
+  if (leapsOptions.given.length > 0) {
+    ctx.fail(`${leapsOptions.given.join(", ")} only ${leapsOptions.given.length > 1 ? "apply" : "applies"} with --leaps.`, `Usage: gloomberb ${LEAPS_USAGE}`);
+  }
+  const raw = requireOneArg(args, OPTIONS_USAGE, "symbol", ctx);
+  let expirationDate: number | undefined;
+  if (expiration != null || rawArgs.includes("--expiration")) {
+    const parsed = expiration == null ? null : parseOptionExpiration(expiration);
+    if (parsed == null) {
+      ctx.fail(
+        expiration == null ? "--expiration needs a date." : `Invalid --expiration "${expiration}".`,
+        `Use YYYY-MM-DD (2028-01-21) or Unix seconds (1832025600).\nUsage: gloomberb ${OPTIONS_USAGE}`,
+      );
+    }
+    expirationDate = parsed;
+  }
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const { symbol, exchange } = listing.request;
-    const expirationDate = expiration == null ? undefined : Number(expiration);
+    const refresh = ctx.cliOptions.refresh;
     const quotePromise = loadListingQuote(market.dataProvider, listing);
-    const { result, chain } = await loadForListing(listing, market, ctx, async () => {
+    const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
+    const { result, chain: loaded } = await loadForListing(listing, market, ctx, async () => {
       const cached = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expirationDate, undefined])
-        .load({ force: ctx.cliOptions.refresh });
+        .load({ force: refresh });
       return {
         result: cached,
         chain: cached?.value ?? await market.dataProvider.getOptionsChain(symbol, exchange, expirationDate, {
-          cacheMode: ctx.cliOptions.refresh ? "refresh" : "default",
+          cacheMode: refresh ? "refresh" : "default",
         }),
       };
+    }, undefined, { command: "options", noun: "options chain" }).catch((error: unknown) => {
+      if (!isOptionsUnavailableError(error)) throw error;
+      // A future or commodity with no chain of its own: name the listed fund whose options stand in.
+      const alternative = listedOptionsAlternative(listing.key);
+      return ctx.fail(optionsUnavailableTitle(listing.key), alternative
+        ? `Nearest listed alternative: ${alternative.symbol} (${alternative.name}), gloomberb options ${alternative.symbol}.`
+          + ` Strategy payoffs: gloomberb fn OSA ${alternative.symbol}`
+        : "Strategy payoffs on a listed underlying: gloomberb fn OSA <ticker>");
     });
+    const inputs = await inputsPromise;
+    if (expirationDate != null && !chainHasExpiry(loaded, expirationDate)) {
+      // An unlisted date comes back as an empty chain; its own list of expiries, else the default chain's, says what to pick.
+      const listed = loaded.expirationDates.length > 0 ? loaded.expirationDates : await market.dataProvider
+        .getOptionsChain(symbol, exchange, undefined, { cacheMode: "default" })
+        .then((fallback) => fallback.expirationDates, () => []);
+      const miss = missingExpiryMessage(listing.key, expirationDate, listed);
+      ctx.fail(miss.message, miss.details);
+    }
     const identity = listingIdentity(listing, await quotePromise);
+    const chain = chainWithModelFigures(loaded, inputs);
     // A failed refresh falls back to the stored chain, which can be days old.
     const refreshWarning = result?.refreshError == null ? null
       : `Options refresh failed; showing the chain stored ${new Date(result.fetchedAt).toISOString()}`
         + (chain.asOf ? ` (last trade ${chain.asOf})` : "");
     const sessionWarning = refreshWarning ? null : priorSessionChainWarning(chain, identity.exchange, Date.now());
-    const warnings = refreshWarning ? [refreshWarning] : sessionWarning ? [sessionWarning] : undefined;
+    const modelWarning = inputs.spot == null && (chain.calls.length > 0 || chain.puts.length > 0)
+      ? `IV and delta need a current ${listing.key} quote; those columns are blank`
+      : null;
+    const warnings = [refreshWarning ?? sessionWarning, modelWarning].filter((warning): warning is string => warning != null);
     // Dated by the chain's last trade; a chain that failed to refresh is the stored one, stale.
     const freshness = rowsFreshness([], { asOf: chain.asOf ?? null }, {
       ...(chain.dataSource ? { dataSource: chain.dataSource } : {}),
       ...(chain.delayMinutes != null ? { delayMinutes: chain.delayMinutes } : {}),
       stale: refreshWarning != null,
     });
-    ctx.printResult({ data: chain, metadata: { ...listingMetadata(identity), expirations: chain.expirationDates }, warnings, freshness }, {
+    ctx.printResult({
+      data: chain,
+      metadata: {
+        ...listingMetadata(identity),
+        expirations: chain.expirationDates,
+        // What `iv` and `delta` on each contract are valued from; the provider's own impliedVolatility is left as sent.
+        model: { spot: inputs.spot ?? null, dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE },
+      },
+      ...(warnings.length > 0 ? { warnings } : {}),
+      freshness,
+    }, {
       heading: listingHeading(identity),
       rows: optionRows,
+      // Choosing an expiry needs the list; once one is chosen the table is that expiry.
+      summary: (data: OptionsChain) => expirationDate == null ? formatExpiryList(data.expirationDates) : "",
+      empty: `No option contracts for ${listingTitle(identity)}.`,
       columns: [
         { key: "side", header: "Side" },
         { key: "contract", header: "Contract", shrink: false },
-        { key: "expiration", header: "Expiry" },
+        // The contract symbol already carries the date, so this goes first when the table is narrow.
+        { key: "expiration", header: "Expiry", optional: true, dropPriority: 2 },
         { key: "strike", header: "Strike", align: "right" },
         { key: "last", header: "Last", align: "right" },
         { key: "bid", header: "Bid", align: "right", format: (_value, row) => formatOptionQuoteCell(row, "bid") },
         { key: "ask", header: "Ask", align: "right", format: (_value, row) => formatOptionQuoteCell(row, "ask") },
-        { key: "volume", header: "Vol", align: "right", format: formatCountCell },
-        { key: "openInterest", header: "OI", align: "right", format: formatCountCell },
+        { key: "iv", header: "IV", align: "right", format: formatOptionIvCell },
+        { key: "delta", header: "Delta", align: "right", format: formatOptionDeltaCell },
+        { key: "volume", header: "Vol", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
+        { key: "openInterest", header: "OI", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
       ],
     });
   });
 }
 
+const FX_USAGE = "fx <currency> | fx <base>/<quote>";
+
 async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
-  const currency = requireArg(rawArgs[0]?.trim().toUpperCase(), "Usage: gloomberb fx <currency>", ctx);
+  const raw = requireOneArg(rawArgs, FX_USAGE, "currency or pair", ctx);
   await withMarketData(ctx, async (market) => {
-    const baseCurrency = market.config.baseCurrency.trim().toUpperCase();
+    const request = parseFxRequest(raw, market.config.baseCurrency);
+    if ("error" in request) return ctx.fail(request.error, `Usage: gloomberb ${FX_USAGE}`);
+    const { currency, baseCurrency } = request;
+    const pair = `${currency}/${baseCurrency}`;
+    const reasons = new Map<string, string>();
     const load = (code: string) => market.dataProvider.getCachedQuery("getExchangeRate", [code])
-      .load({ force: ctx.cliOptions.refresh }).catch(() => null);
-    const legs = currency === baseCurrency ? [] : await Promise.all([load(currency), load(baseCurrency)]);
-    const [from, base] = legs;
-    const rate = currency === baseCurrency ? 1 : from && base ? from.value / base.value : Number.NaN;
-    if (!Number.isFinite(rate) || rate <= 0) ctx.fail(`Exchange rate unavailable for ${currency}/${baseCurrency}`);
+      .load({ force: ctx.cliOptions.refresh }).catch((error) => {
+        const reason = providerMissReason(error);
+        if (reason) reasons.set(code, reason);
+        return null;
+      });
+    // Every rate is a cross of two USD legs; a code priced in itself needs none.
+    const codes = currency === baseCurrency ? [] : [currency, baseCurrency];
+    const legs = await Promise.all(codes.map(load));
+    const missing = codes.filter((_code, index) => !isUsableRate(legs[index]?.value));
+    if (missing.length > 0) {
+      // A reason the data service gave for the first missing leg says more than the generic line.
+      const reason = missing.map((code) => reasons.get(code)).find(Boolean);
+      if (reason) ctx.fail(reason);
+      ctx.fail(
+        `Exchange rate unavailable for ${missing.join(" and ")}.`,
+        `${pair} is crossed from each currency's USD rate, and none came back for ${missing.join(" or ")}. Check the ISO code.`,
+      );
+    }
+    const rate = codes.length === 0 ? 1 : crossRate(legs[0]?.value, legs[1]?.value);
     // A cross rate is only as current as its older leg.
     const observed = legs.flatMap((leg) => leg?.asOf ?? []);
     const asOf = observed.length > 0 ? new Date(Math.min(...observed)).toISOString() : null;
     const stale = legs.some((leg) => leg != null && (leg.staleAt <= Date.now() || leg.refreshError != null));
-    ctx.printResult({ data: [{ currency, baseCurrency, rate, asOf, stale }] }, {
-      layout: "record",
+    const row = { currency, baseCurrency, rate, asOf, stale, pair, inverse: 1 / rate };
+    ctx.printResult({ data: [row] }, {
+      text: () => {
+        const time = asOf ? `As of ${formatUtcTime(asOf)}` : "";
+        const when = stale ? cliStyles.warning(time ? `${time}, stale` : "Stale") : time && cliStyles.muted(time);
+        return [describeFxRate(request, rate), when].filter(Boolean).join("\n");
+      },
       columns: [
         { key: "currency", header: "Currency" },
         { key: "baseCurrency", header: "Base" },
         { key: "rate", header: "Rate", align: "right" },
-        ...(asOf || stale ? [{
-          key: "asOf",
-          header: "As Of",
-          format: (value: unknown, row: { stale: boolean }) => {
-            const time = typeof value === "string" ? formatUtcTime(value) : "";
-            return row.stale ? cliStyles.warning(`${time} stale`.trim()) : time;
-          },
-        }] : []),
+        { key: "asOf", header: "As Of" },
+        { key: "stale", header: "Stale" },
+        { key: "pair", header: "Pair" },
+        { key: "inverse", header: "Inverse", align: "right" },
       ],
     });
   });
@@ -948,7 +1276,7 @@ async function runEarnings(rawArgs: string[], ctx: Parameters<CliCommandDef["exe
   });
 }
 
-export const marketDataCliCommands: CliCommandDef[] = [
+export const marketDataCliCommands: BuiltinCliCommandDef[] = [
   {
     name: "quote",
     description: "Show the latest price for one or more symbols",
@@ -976,26 +1304,67 @@ export const marketDataCliCommands: CliCommandDef[] = [
     description: "Fetch open, high, low, close, and volume over a range",
     help: {
       group: CLI_COMMAND_GROUPS.research,
-      usage: ["history <symbol> [--range <range>]"],
+      usage: [HISTORY_USAGE],
       options: [
-        { flags: "--range <range>", description: `${TIME_RANGES.join(", ")} (default 1Y)` },
+        { flags: "--range <range>", description: `${TIME_RANGES.join(", ")} (default 1Y); ${HISTORY_ALL_RANGE}` },
         EXCHANGE_OPTION,
       ],
-      examples: ["history AAPL", "history BHP:ASX --range 5Y", "history AAPL --range 5Y --csv > aapl.csv"],
+      sections: [{
+        title: "Bars",
+        lines: [
+          `Each range comes in one bar size: ${historyIntervalsByRange()}. The line under the heading, and the --json metadata, give the currency, the bar size actually served, the first and last bar and the bar count. A warning says when the bars are coarser, or start later, than the range asked for.`,
+          "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. Every exported row (--csv, --ndjson, --json) carries currency, interval and flag.",
+        ],
+      }],
+      examples: ["history AAPL", "history BHP:ASX --range 5Y", "history ZAR=X --range ALL", "history ZAR=X --tail 5", "history AAPL --range 5Y --csv > aapl.csv"],
     },
+    unknownOptionHint: (flag) => DATE_WINDOW_OPTIONS.has(flag)
+      ? `history takes a --range instead of dates: ${TIME_RANGES.join(", ")}. ${HISTORY_ALL_RANGE}.`
+      : null,
     execute: runHistory,
   },
   {
     name: "options",
-    description: "Fetch an options chain",
+    description: "Fetch an options chain, or rank LEAPS across symbols",
     help: {
       group: CLI_COMMAND_GROUPS.research,
-      usage: ["options <symbol> [--expiration <unix>]"],
+      usage: [OPTIONS_USAGE, LEAPS_USAGE],
       options: [
-        { flags: "--expiration <unix>", description: "Expiration as Unix seconds; defaults to the nearest one" },
+        {
+          flags: "--expiration <YYYY-MM-DD|unix>",
+          description: "Expiration as a date (2028-01-21) or Unix seconds; defaults to the nearest one, and lists the others",
+        },
         EXCHANGE_OPTION,
+        { flags: "--leaps", description: "Rank contracts more than a year out across the symbols given, as a stock replacement" },
+        { flags: "--side <calls|puts>", description: `With --leaps: the side to rank (default ${DEFAULT_LEAPS_CRITERIA.side}s)` },
+        {
+          flags: "--delta <low-high>",
+          description: `With --leaps: absolute delta band (default ${DEFAULT_LEAPS_CRITERIA.minDelta.toFixed(2)}-${DEFAULT_LEAPS_CRITERIA.maxDelta.toFixed(2)})`,
+        },
+        {
+          flags: "--max-spread <percent>",
+          description: `With --leaps: widest bid/ask spread, in percent of the midpoint (default ${DEFAULT_LEAPS_CRITERIA.maxSpreadPercent})`,
+        },
+        { flags: "--min-oi <contracts>", description: `With --leaps: least open interest (default ${DEFAULT_LEAPS_CRITERIA.minOpenInterest})` },
+        {
+          flags: "--sort <order>",
+          description: "With --leaps: carry (extrinsic per year, lowest first; the default), spread, oi, delta, expiry or symbol",
+        },
+      ],
+      sections: [{
+        title: "LEAPS",
+        lines: [
+          "--leaps reads every expiry more than a year out for each symbol and keeps the liquid contracts in the delta band, ranked by extrinsic per year: time value (midpoint less intrinsic) as a percent of spot, per year to expiry.",
+          "A symbol without LEAPS, a quote or a chain is named in a warning and the others still rank. docs/research-data.md defines each figure.",
+        ],
+      }],
+      examples: [
+        "options AAPL",
+        "options AAPL --expiration 2028-01-21",
+        "options AAPL:NASDAQ --json",
+        "options AAPL MSFT NVDA GOOGL AMZN META --leaps",
+        "options SPY QQQ --leaps --side puts --delta 0.20-0.40 --csv",
       ],
-      examples: ["options AAPL", "options AAPL:NASDAQ --json"],
     },
     execute: runOptions,
   },
@@ -1032,8 +1401,8 @@ export const marketDataCliCommands: CliCommandDef[] = [
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["financials <symbol>"],
-      options: [EXCHANGE_OPTION],
-      examples: ["financials MSFT", "financials SAN:EPA", "financials MSFT --json"],
+      options: [EXCHANGE_OPTION, TABLE_SECTION_OPTION],
+      examples: ["financials MSFT", "financials SAN:EPA", "financials MSFT --json", "financials MSFT --csv > msft.csv"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "statements"),
   },
@@ -1043,8 +1412,8 @@ export const marketDataCliCommands: CliCommandDef[] = [
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["fundamentals <symbol>"],
-      options: [EXCHANGE_OPTION],
-      examples: ["fundamentals NVDA", "fundamentals ASML:AMS"],
+      options: [EXCHANGE_OPTION, TABLE_SECTION_OPTION],
+      examples: ["fundamentals NVDA", "fundamentals ASML:AMS", "fundamentals NVDA --csv --section fundamentals"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "fundamentals"),
   },
@@ -1054,8 +1423,8 @@ export const marketDataCliCommands: CliCommandDef[] = [
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["valuation <symbol>"],
-      options: [EXCHANGE_OPTION],
-      examples: ["valuation NVDA", "valuation BP:LSE"],
+      options: [EXCHANGE_OPTION, TABLE_SECTION_OPTION],
+      examples: ["valuation NVDA", "valuation BP:LSE", "valuation NVDA --csv"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "valuation"),
   },
@@ -1164,11 +1533,18 @@ export const marketDataCliCommands: CliCommandDef[] = [
   },
   {
     name: "fx",
-    description: "Convert a currency into your base currency",
+    description: "Convert a currency into your base currency, or quote a pair such as USD/NGN",
     help: {
       group: CLI_COMMAND_GROUPS.markets,
-      usage: ["fx <currency>"],
-      examples: ["fx EUR", "fx JPY --json"],
+      usage: ["fx <currency>", "fx <base>/<quote>"],
+      sections: [{
+        title: "Direction",
+        lines: [
+          "A bare code is one unit of it in your base currency. A pair reads as markets quote it: USD/NGN is how many NGN one USD buys. Two codes neither of which is USD, such as ZAR/NGN, cross through their USD rates.",
+          "The answer states both directions: 1 NGN = 0.000752791 USD  (USD/NGN 1328.39). --json, --csv and --ndjson carry rate (base currency per currency), pair, inverse, asOf and stale.",
+        ],
+      }],
+      examples: ["fx EUR", "fx NGN", "fx USD/NGN", "fx ZAR/NGN", "fx JPY --json"],
     },
     execute: runFx,
   },