gloomberb 0.16.0 → 0.16.2

package/src/cli/commands/market.ts

@@ -1,6 +1,6 @@
 import type { CliCommandDef } from "../../types/plugin";
 import { TIME_RANGES, type TimeRange } from "../../time-series/range";
-import type { EarningsEvent, QuoteBatchResult, SecFilingItem } from "../../types/data-provider";
+import type { EarningsEvent, QuoteBatchResult, QuoteSubscriptionTarget, SecFilingItem } from "../../types/data-provider";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
 import type {
   AnalystResearchData,
@@ -13,7 +13,7 @@ import { currencyMinorDigits, formatMarketPrice, formatMarketPriceWithCurrency,
 import { getActiveQuoteDisplay, marketStateLabel } from "../../market-data/market/status";
 import { formatCompact, formatDistributionAmount, formatPercent } from "../../utils/format";
 import { withCliServices, withMarketData } from "../context";
-import { isoDate, parsePositiveInt, requireArg, takeOption } from "./command-utils";
+import { isoDate, parsePositiveInt, requireArg, takeFlag, takeOption } from "./command-utils";
 import { CLI_COMMAND_GROUPS } from "../help";
 import {
   formatChangePercentCell,
@@ -35,12 +35,57 @@ 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 { CRYPTO_BOARD_HINT, quoteNotes } from "./crypto-hints";
+import { formatUtcTime } from "../../utils/utc-time";
+import { exportedFundamentals } from "../../utils/price-earnings";
+import { fundamentalsFreshness, quotesFreshness, rowsFreshness } from "../freshness";
+import {
+  barHistoryFreshness,
+  barResolutionFromDates,
+  REPORTED_DATA,
+  SEC_FILINGS,
+} from "../../plugins/builtin/shared/report-freshness";
+import {
+  EXCHANGE_OPTION,
+  listingHeading,
+  listingIdentity,
+  listingTitle,
+  listingVenues,
+  loadForListing,
+  loadListingQuote,
+  notTradedMessage,
+  requireCliListing,
+  type CliListing,
+  type ListingIdentity,
+} from "../listing-arg";
+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 {
+  holderListFacts,
+  holderValueBasis,
+  moneyColumnHeader,
+  nonUsHolderCaveat,
+  sharedReportDate,
+} from "../../plugins/builtin/holders/report-header";
+import { fetchBeneficialOwners } from "../../plugins/builtin/holders/beneficial-client";
+import { filingFormMatches, SEC_FILING_FETCH_LIMIT } from "../../plugins/builtin/sec/forms";
+import {
+  BENEFICIAL_REPORT_COLUMNS,
+  beneficialCoverageNotices,
+  beneficialListComplete,
+  beneficialListFacts,
+  beneficialListUnreadable,
+  beneficialRouteForm,
+  buildBeneficialReportRows,
+  HOLDER_FORMS,
+  parseHolderForm,
+  type HolderForm,
+} from "../../plugins/builtin/holders/beneficial-report";
 
 const VALID_RANGES = new Set<TimeRange>(TIME_RANGES);
-const EXCHANGE_OPTION = {
-  flags: "--exchange <code>",
-  description: "Listing exchange, for a symbol that trades in several places",
-};
 const VALID_NEWS_FEEDS = new Set<NewsFeed>(["latest", "top", "breaking", "ticker", "sector", "topic"]);
 
 type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & { error: string | null };
@@ -67,6 +112,11 @@ function normalizeSymbols(args: string[]): string[] {
     .filter(Boolean);
 }
 
+/** What JSON metadata says about the listing a command resolved. */
+function listingMetadata(identity: ListingIdentity) {
+  return { symbol: identity.symbol, exchange: identity.exchange || null, name: identity.name };
+}
+
 const QUOTE_LEAD_COLUMNS = [
   { key: "symbol", header: "Symbol" },
   { key: "name", header: "Name" },
@@ -86,7 +136,8 @@ function quoteColumns() {
   return [
     ...QUOTE_LEAD_COLUMNS,
     { key: "currency", header: "Cur" },
-    { key: "source", header: "Source" },
+    // 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" },
   ];
 }
@@ -332,40 +383,78 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
   if (symbols.length === 0) ctx.fail(`Usage: gloomberb ${commandName} <symbol...>`);
 
   await withMarketData(ctx, async (market) => {
-    const results = await market.dataProvider.getQuotesBatch(
-      symbols.map((symbol) => ({ symbol, exchange })),
-      { forceRefresh: ctx.cliOptions.refresh },
-    );
-    const data = results.map((result) => ({
+    // With several symbols, --exchange is for the ones that name no exchange of their own.
+    const listings = await Promise.all(symbols.map((symbol) => requireCliListing(
+      symbol, exchange, market, ctx, { ownExchangeWins: symbols.length > 1 },
+    )));
+    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]);
+    // 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) => ({
       target: result.target,
+      listing: listingMetadata(listingIdentity(listingOf(result, index), result.quote)),
       quote: result.quote,
-      error: errorMessage(result.error),
+      error: notTraded[index] ?? errorMessage(result.error),
     }));
-    ctx.printResult({ data }, { rows: quoteRows, columns: commandName === "compare" ? compareColumns() : quoteColumns() });
+    // Text mode shows only "unavailable" in the cell; the JSON rows already carry each reason.
+    const notes = ctx.cliOptions.format === "text" ? quoteNotes(data, { exchange }) : [];
+    ctx.printResult({
+      data,
+      warnings: notes.length > 0 ? notes : undefined,
+      freshness: quotesFreshness(data.map((row) => row.quote)),
+    }, {
+      rows: quoteRows,
+      columns: commandName === "compare" ? compareColumns() : quoteColumns(),
+    });
   });
 }
 
+/** 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);
+}
+
 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 symbol = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb history <symbol> [--range <range>]", ctx);
+  const requestedExchange = takeOption(args, "--exchange");
+  const raw = requireArg(args[0], "Usage: gloomberb history <symbol> [--range <range>]", ctx);
   await withMarketData(ctx, async (market) => {
-    const localTicker = requestedExchange ? null : await market.store.loadTicker(symbol);
-    const exchange = requestedExchange || localTicker?.metadata.exchange || "";
+    const listing = await requireCliListing(raw, requestedExchange, market, ctx);
+    const { symbol, exchange } = listing.request;
     const context = { cacheMode: ctx.cliOptions.refresh ? "refresh" as const : "default" as const };
-    const { points, resolution } = market.dataProvider.getPriceHistoryWithMetadata
-      ? await market.dataProvider.getPriceHistoryWithMetadata(symbol, exchange, range, context)
-      : { points: await market.dataProvider.getPriceHistory(symbol, exchange, range, context), resolution: null };
+    const load = () => market.dataProvider.getPriceHistoryWithMetadata
+      ? 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)
+        .catch((error) => failHistory(error, listing.key, ctx)),
+      loadListingQuote(market.dataProvider, listing),
+    ]);
+    const identity = listingIdentity(listing, quote);
     const data = historyRows(points, resolution);
-    const decimals = historyPriceDecimals(data, localTicker?.metadata.assetCategory);
+    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.
     const intraday = data.some((row) => row.date.length > 10);
-    ctx.printResult({ data, metadata: { symbol, range, exchange, resolution } }, {
+    // A bar history: dated by its last bar, stale once bars of its size stop arriving.
+    const freshness = rowsFreshness(data, {
+      ...barHistoryFreshness(intraday ? null : barResolutionFromDates(data.map((row) => row.date))),
+      observedKey: "date",
+      oldest: null,
+    });
+    ctx.printResult({ data, metadata: { ...listingMetadata(identity), range, resolution }, freshness }, {
+      heading: listingHeading(identity),
       columns: [
         intraday
-          ? { key: "date", header: "Time (UTC)", format: (value) => typeof value === "string" ? value.slice(0, 16).replace("T", " ") : "" }
+          ? { 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 },
@@ -381,34 +470,44 @@ type FinancialsView = "statements" | "fundamentals" | "valuation";
 
 async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1], view: FinancialsView) {
   const args = [...rawArgs];
-  const exchange = takeOption(args, "--exchange") ?? "";
+  const exchangeOption = takeOption(args, "--exchange");
   const commandName = view === "statements" ? "financials" : view;
-  const symbol = requireArg(args[0]?.toUpperCase(), `Usage: gloomberb ${commandName} <symbol>`, ctx);
+  const raw = requireArg(args[0], `Usage: gloomberb ${commandName} <symbol>`, ctx);
   await withMarketData(ctx, async (market) => {
-    const financials = await market.dataProvider.getTickerFinancials(symbol, exchange, {
-      cacheMode: ctx.cliOptions.refresh ? "refresh" : "default",
-    });
+    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" },
+    ));
+    const identity = listingIdentity(listing, financials.quote);
     const data: FinancialsCliData = {
-      symbol,
-      exchange,
+      symbol: listing.key,
+      exchange: identity.exchange,
       providerId: financials.quote?.providerId ?? null,
       ...financials,
     };
     if (view !== "statements") {
-      ctx.printResult({ data }, { text: (financialsData) => renderFundamentalsReport(financialsData, view) });
+      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) });
       return;
     }
     ctx.printResult({
       data,
       metadata: {
-        symbol,
+        ...listingMetadata(identity),
         providerId: financials.quote?.providerId,
         annualStatements: financials.annualStatements.length,
         quarterlyStatements: financials.quarterlyStatements.length,
-        fundamentals: financials.fundamentals,
+        fundamentals: exportedFundamentals(financials.fundamentals),
         profile: financials.profile,
       },
+      freshness: rowsFreshness(financialStatementRows(data), {
+        ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null,
+      }),
     }, {
+      heading: listingHeading(identity),
       rows: financialStatementRows,
       columns: [
         { key: "date", header: "Date" },
@@ -426,24 +525,39 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
 async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const feed = parseNewsFeed(takeOption(args, "--feed"));
-  const ticker = args[0]?.toUpperCase();
+  const exchangeOption = takeOption(args, "--exchange");
+  if (exchangeOption && !args[0]) ctx.fail("--exchange needs a symbol: gloomberb news <symbol> --exchange <code>");
   await withMarketData(ctx, async (market) => {
+    const listing = args[0] ? await requireCliListing(args[0], exchangeOption, market, ctx) : null;
     const limit = ctx.cliOptions.limit ?? 20;
-    const articles = await market.dataProvider.getNews({
-      feed: feed ?? (ticker ? "ticker" : "latest"),
+    const loadNews = () => market.dataProvider.getNews({
+      feed: feed ?? (listing ? "ticker" : "latest"),
       // Still set for news plugins that read the deprecated scope.
-      scope: ticker ? "ticker" : "global",
-      ticker,
+      scope: listing ? "ticker" : "global",
+      ticker: listing?.request.symbol,
+      exchange: listing?.request.exchange || undefined,
       limit,
     });
-    ctx.printResult({ data: articles, metadata: { ticker: ticker ?? null, feed: feed ?? null } }, {
+    const [articles, quote] = await Promise.all([
+      listing ? loadForListing(listing, market, ctx, loadNews, (found) => found.length === 0) : loadNews(),
+      listing ? loadListingQuote(market.dataProvider, listing) : null,
+    ]);
+    const identity = listing ? listingIdentity(listing, quote) : null;
+    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,
+      }),
+    }, {
+      ...(identity ? { heading: listingHeading(identity) } : {}),
       rows: newsRows,
       columns: [
-        // UTC, as the news panes print it, rather than the host zone unlabeled.
+        // UTC with the zone named, as every CLI time prints, rather than the host zone unlabeled.
         {
           key: "publishedAt",
-          header: "Published (UTC)",
-          format: (value) => typeof value === "string" ? value.slice(0, 16).replace("T", " ") : "",
+          header: "Published",
+          format: (value) => typeof value === "string" ? formatUtcTime(value) : "",
         },
         { key: "source", header: "Source", maxWidth: 20 },
         { key: "title", header: "Title" },
@@ -454,22 +568,67 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   });
 }
 
+const FILING_COLUMNS = [
+  { key: "filingDate", header: "Date" },
+  { key: "form", header: "Form" },
+  { key: "companyName", header: "Company", maxWidth: 24 },
+  { key: "url", header: "URL", optional: true },
+];
+
+/** The US listing the SEC files a symbol under, from the symbol's venues: NYSE for SAN's Banco Santander. */
+async function registrantUsExchange(market: MarketContext, symbol: string, registrantName: string): Promise<string | null> {
+  const venues = (await listingVenues(symbol, market).catch(() => []))
+    .filter((venue) => !nonUsSecListingVenue(symbol, venue.exchange) && !areDifferentCompanies(venue.name, registrantName));
+  return (venues.find((venue) => isUsListingExchange(venue.exchange)) ?? venues[0])?.exchange ?? null;
+}
+
 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);
-  const exchange = takeOption(args, "--exchange") ?? "";
-  const symbol = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb filings <symbol>", ctx);
+  const exchangeOption = takeOption(args, "--exchange");
+  const form = takeOption(args, "--form")?.trim() || null;
+  const raw = requireArg(args[0], "Usage: gloomberb filings <symbol>", ctx);
   await withMarketData(ctx, async (market) => {
-    const filings = await market.dataProvider.getSecFilings(symbol, count, exchange);
-    ctx.printResult({ data: filings, metadata: { symbol } }, {
-      rows: filingRows,
-      columns: [
-        { key: "filingDate", header: "Date" },
-        { key: "form", header: "Form" },
-        { key: "companyName", header: "Company", maxWidth: 24 },
-        { key: "url", header: "URL", optional: true },
-      ],
-    });
+    const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    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 identity = nonUsSecListingVenue(symbol, exchange) ? listingIdentity(listing, await quotePromise) : null;
+    try {
+      const context = identity?.name ? { listingName: identity.name } : undefined;
+      const [filings, quote] = await Promise.all([
+        loadForListing(listing, market, ctx, () => form
+          // A form filter searches every filing the service lists for the issuer, as the SEC pane does.
+          ? market.dataProvider.getSecFilings(symbol, SEC_FILING_FETCH_LIMIT, exchange, context)
+            .then((all) => all.filter((filing) => filingFormMatches(filing.form, form)).slice(0, count))
+          : market.dataProvider.getSecFilings(symbol, count, exchange, context),
+        (found) => found.length === 0),
+        quotePromise,
+      ]);
+      const resolved = identity ?? listingIdentity(listing, quote);
+      ctx.printResult({
+        data: filings,
+        metadata: { ...listingMetadata(resolved), ...(form ? { form } : {}) },
+        freshness: rowsFreshness(filingRows(filings), { ...SEC_FILINGS, observedKey: "filingDate" }),
+      }, {
+        heading: listingHeading(resolved),
+        rows: filingRows,
+        columns: FILING_COLUMNS,
+        empty: form ? `No ${form} filings found for ${listingTitle(resolved)}.` : `No SEC filings found for ${listingTitle(resolved)}.`,
+      });
+    } catch (error) {
+      if (!(error instanceof SecRegistrantMismatchError)) throw error;
+      // Another company's filings never show under this listing; say whose they were.
+      const message = secRegistrantMismatchMessage(
+        error.listing, error.registrantName, await registrantUsExchange(market, error.listing.symbol, error.registrantName),
+      );
+      const resolved = identity ?? listingIdentity(listing, await quotePromise);
+      ctx.printResult({
+        data: [] as SecFilingItem[],
+        metadata: { ...listingMetadata(resolved), secRegistrant: error.registrantName },
+        warnings: ctx.cliOptions.format === "text" ? undefined : [message],
+      }, { rows: filingRows, columns: FILING_COLUMNS, empty: message });
+    }
   });
 }
 
@@ -487,6 +646,52 @@ function insiderSummary(data: HolderData, ownerTypes: Set<string>): string {
   return [share, transactions].filter(Boolean).join("\n");
 }
 
+/** `holders --form 13d|13g|all`: the 13D/13G beneficial owners, joined by name to the 13F holders. */
+async function printBeneficialOwners(
+  listing: CliListing,
+  market: MarketContext,
+  form: Exclude<HolderForm, "13f">,
+  history: boolean,
+  ctx: Parameters<CliCommandDef["execute"]>[1],
+) {
+  const { symbol, exchange } = listing.request;
+  const [payload, holders, quote] = await Promise.all([
+    loadForListing(listing, market, ctx, () => fetchBeneficialOwners(symbol, { form: beneficialRouteForm(form), history })),
+    market.dataProvider.getHolders?.(symbol, exchange).catch(() => null) ?? null,
+    loadListingQuote(market.dataProvider, listing),
+  ]);
+  const identity = listingIdentity(listing, quote);
+  const rows = buildBeneficialReportRows(payload, { history, holders });
+  const notices = beneficialCoverageNotices(payload.coverage);
+  ctx.printResult({
+    data: rows,
+    ...(notices.length ? { warnings: notices } : {}),
+    metadata: {
+      ...listingMetadata(identity),
+      name: identity.name ?? (payload.companyName || null),
+      cik: payload.cik || null,
+      form,
+      history,
+      asOf: payload.asOf,
+      coverage: payload.coverage,
+      complete: beneficialListComplete(payload),
+    },
+  }, {
+    heading: `${listingHeading(identity)}${cliStyles.muted(beneficialListFacts(payload, form, rows.length, history).map((fact) => `  ·  ${fact}`).join(""))}`,
+    textColumns: BENEFICIAL_REPORT_COLUMNS,
+    columns: [
+      ...BENEFICIAL_REPORT_COLUMNS,
+      { key: "status", header: "Status" },
+      { key: "filerCik", header: "Filer CIK" },
+      { key: "accessionNumber", header: "Accession" },
+      { key: "filingUrl", header: "URL" },
+    ],
+    empty: beneficialListUnreadable(payload)
+      ? `13D/13G filings for ${listingTitle(identity)} are listed but could not be read.`
+      : `No 13D/13G filings in the last 4 years for ${listingTitle(identity)}.`,
+  });
+}
+
 async function runHolders(
   rawArgs: string[],
   ctx: Parameters<CliCommandDef["execute"]>[1],
@@ -494,43 +699,98 @@ async function runHolders(
   ownerTypes?: Set<string>,
 ) {
   const args = [...rawArgs];
-  const exchange = takeOption(args, "--exchange") ?? "";
-  const symbol = requireArg(args[0]?.toUpperCase(), `Usage: gloomberb ${commandName} <symbol>`, ctx);
+  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 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.");
   await withMarketData(ctx, async (market) => {
-    const data = await market.dataProvider.getHolders(symbol, exchange);
-    ctx.printResult({ data, metadata: { symbol, summary: data.summary } }, {
-      rows: (holderData) => holderRows(holderData, ownerTypes),
+    const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    if (form !== "13f") return printBeneficialOwners(listing, market, form, history, ctx);
+    const [data, quote] = await Promise.all([
+      loadForListing(
+        listing, market, ctx,
+        () => market.dataProvider.getHolders(listing.request.symbol, listing.request.exchange),
+        (found) => found.holders.length === 0,
+      ),
+      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 institutional = !ownerTypes?.has("insider");
+    const total = institutional ? data.summary?.institutionsCount ?? null : null;
+    const reportDate = sharedReportDate(rows);
+    const valueBasis = rows.length > 0 ? holderValueBasis(reportDate) : null;
+    const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(identity.exchange || data.exchange, data.currency) : null;
+    // 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 });
+    ctx.printResult({
+      data,
+      metadata: {
+        ...listingMetadata(identity),
+        summary: data.summary,
+        currency: data.currency ?? null,
+        asOf: data.asOf ?? null,
+        shown,
+        reported: rows.length,
+        total,
+        truncated: shown < (total ?? rows.length),
+        valueBasis,
+        positionsBasis,
+      },
+    }, {
+      heading: `${listingHeading(identity)}${cliStyles.muted(facts.map((fact) => `  ·  ${fact}`).join(""))}`,
+      rows: () => rows,
       columns: [
         { key: "type", header: "Type" },
         { key: "name", header: "Holder" },
         { key: "reportDate", header: "Date" },
         { key: "shares", header: "Shares", align: "right", format: formatCountCell },
-        { key: "value", header: "Value", align: "right", value: (row) => row.value == null ? "" : formatCompact(Number(row.value)) },
+        {
+          key: "value",
+          header: moneyColumnHeader("Value", data.currency),
+          align: "right",
+          value: (row) => row.value == null ? "" : formatCompact(Number(row.value)),
+        },
         { key: "percentHeld", header: "% Held", align: "right", format: formatFractionPercentCell },
       ],
-      ...(commandName === "insider" && ownerTypes
-        ? { summary: (holderData: HolderData) => insiderSummary(holderData, ownerTypes) }
-        : {}),
-      empty: `No holders reported for ${symbol}.`,
+      summary: (holderData: HolderData) => [
+        [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? ""].filter(Boolean).join(" "),
+        commandName === "insider" && ownerTypes ? insiderSummary(holderData, ownerTypes) : "",
+      ].filter(Boolean).join("\n"),
+      empty: `No holders reported for ${listingTitle(identity)}.`,
     });
   });
 }
 
 async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
-  const exchange = takeOption(args, "--exchange") ?? "";
-  const symbol = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb analyst <symbol>", ctx);
+  const exchangeOption = takeOption(args, "--exchange");
+  const raw = requireArg(args[0], "Usage: gloomberb analyst <symbol>", ctx);
   await withMarketData(ctx, async (market) => {
-    const data = await market.dataProvider.getAnalystResearch(symbol, exchange);
+    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)),
+      loadListingQuote(market.dataProvider, listing),
+    ]);
+    const identity = listingIdentity(listing, quote);
     ctx.printResult({
       data,
       metadata: {
-        symbol,
+        ...listingMetadata(identity),
         recommendationRating: data.recommendationRating,
         priceTarget: data.priceTarget,
         recommendations: data.recommendations,
       },
+      freshness: rowsFreshness(analystRows(data), {
+        ...REPORTED_DATA, basis: "analyst ratings", observedKey: "date", oldest: null,
+      }, { stale: data.stale === true }),
     }, {
+      heading: listingHeading(identity),
       rows: analystRows,
       summary: analystSummary,
       columns: [
@@ -546,11 +806,23 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
 
 async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
-  const exchange = takeOption(args, "--exchange") ?? "";
-  const symbol = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb events <symbol>", ctx);
+  const exchangeOption = takeOption(args, "--exchange");
+  const raw = requireArg(args[0], "Usage: gloomberb events <symbol>", ctx);
   await withMarketData(ctx, async (market) => {
-    const data = await market.dataProvider.getCorporateActions(symbol, exchange);
-    ctx.printResult({ data, metadata: { symbol } }, {
+    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)),
+      loadListingQuote(market.dataProvider, listing),
+    ]);
+    const identity = listingIdentity(listing, quote);
+    ctx.printResult({
+      data,
+      metadata: listingMetadata(identity),
+      freshness: rowsFreshness(corporateActionRows(data), {
+        ...REPORTED_DATA, basis: "corporate actions", observedKey: "date", oldest: null,
+      }),
+    }, {
+      heading: listingHeading(identity),
       rows: corporateActionRows,
       columns: [
         { key: "date", header: "Date" },
@@ -564,22 +836,38 @@ async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execu
 async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const expiration = takeOption(args, "--expiration");
-  const exchange = takeOption(args, "--exchange") ?? "";
-  const symbol = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb options <symbol> [--expiration <unix>]", ctx);
+  const exchangeOption = takeOption(args, "--exchange");
+  const raw = requireArg(args[0], "Usage: gloomberb options <symbol> [--expiration <unix>]", ctx);
   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 result = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expirationDate, undefined])
-      .load({ force: ctx.cliOptions.refresh });
-    const chain = result?.value ?? await market.dataProvider.getOptionsChain(symbol, exchange, expirationDate, {
-      cacheMode: ctx.cliOptions.refresh ? "refresh" : "default",
+    const quotePromise = loadListingQuote(market.dataProvider, listing);
+    const { result, chain } = await loadForListing(listing, market, ctx, async () => {
+      const cached = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expirationDate, undefined])
+        .load({ force: ctx.cliOptions.refresh });
+      return {
+        result: cached,
+        chain: cached?.value ?? await market.dataProvider.getOptionsChain(symbol, exchange, expirationDate, {
+          cacheMode: ctx.cliOptions.refresh ? "refresh" : "default",
+        }),
+      };
     });
+    const identity = listingIdentity(listing, await quotePromise);
     // 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, exchange, Date.now());
+    const sessionWarning = refreshWarning ? null : priorSessionChainWarning(chain, identity.exchange, Date.now());
     const warnings = refreshWarning ? [refreshWarning] : sessionWarning ? [sessionWarning] : undefined;
-    ctx.printResult({ data: chain, metadata: { symbol, expirations: chain.expirationDates }, warnings }, {
+    // 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 }, {
+      heading: listingHeading(identity),
       rows: optionRows,
       columns: [
         { key: "side", header: "Side" },
@@ -619,9 +907,10 @@ async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]
         ...(asOf || stale ? [{
           key: "asOf",
           header: "As Of",
-          format: (value: unknown, row: { stale: boolean }) => (
-            row.stale ? cliStyles.warning(`${value ?? ""} stale`.trim()) : String(value ?? "")
-          ),
+          format: (value: unknown, row: { stale: boolean }) => {
+            const time = typeof value === "string" ? formatUtcTime(value) : "";
+            return row.stale ? cliStyles.warning(`${time} stale`.trim()) : time;
+          },
         }] : []),
       ],
     });
@@ -629,11 +918,23 @@ async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]
 }
 
 async function runEarnings(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
-  const symbols = normalizeSymbols([...rawArgs]);
+  const args = [...rawArgs];
+  const exchangeOption = takeOption(args, "--exchange");
+  const symbols = normalizeSymbols(args);
   if (symbols.length === 0) ctx.fail("Usage: gloomberb earnings <symbol...>");
   await withCliServices(ctx, async (services) => {
-    const events = await services.dataProvider.getEarningsCalendar(symbols);
-    ctx.printResult({ data: events }, {
+    const listings = await Promise.all(symbols.map((symbol) => requireCliListing(
+      symbol, exchangeOption, services, ctx, { ownExchangeWins: symbols.length > 1 },
+    )));
+    const events = await loadForListing(
+      listings, services, ctx,
+      () => services.dataProvider.getEarningsCalendar(listings.map((listing) => listing.key)),
+      (found) => found.length === 0,
+    );
+    ctx.printResult({
+      data: events,
+      freshness: rowsFreshness(earningsRows(events), { status: "not-a-feed", basis: "calendar", observedKey: "date", oldest: null }),
+    }, {
       rows: earningsRows,
       columns: [
         { key: "date", header: "Date" },
@@ -655,7 +956,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.research,
       usage: ["quote <symbol...>"],
       options: [EXCHANGE_OPTION],
-      examples: ["quote AAPL MSFT NVDA", "quote BTC-USD EURUSD=X", "quote AAPL --json"],
+      examples: ["quote AAPL MSFT NVDA", "quote SAN:EPA BHP:ASX", "quote BTC-USD EURUSD=X", "quote AAPL --json"],
     },
     execute: (args, ctx) => runQuote(args, ctx, "quote"),
   },
@@ -666,7 +967,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.research,
       usage: ["compare <symbol...>"],
       options: [EXCHANGE_OPTION],
-      examples: ["compare KO PEP", "compare SPY QQQ IWM --csv"],
+      examples: ["compare KO PEP", "compare SAN:EPA SAN:NYSE", "compare SPY QQQ IWM --csv"],
     },
     execute: (args, ctx) => runQuote(args, ctx, "compare"),
   },
@@ -680,7 +981,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
         { flags: "--range <range>", description: `${TIME_RANGES.join(", ")} (default 1Y)` },
         EXCHANGE_OPTION,
       ],
-      examples: ["history AAPL", "history AAPL --range 5Y --csv > aapl.csv"],
+      examples: ["history AAPL", "history BHP:ASX --range 5Y", "history AAPL --range 5Y --csv > aapl.csv"],
     },
     execute: runHistory,
   },
@@ -694,7 +995,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
         { flags: "--expiration <unix>", description: "Expiration as Unix seconds; defaults to the nearest one" },
         EXCHANGE_OPTION,
       ],
-      examples: ["options AAPL", "options AAPL --json"],
+      examples: ["options AAPL", "options AAPL:NASDAQ --json"],
     },
     execute: runOptions,
   },
@@ -732,7 +1033,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["financials <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["financials MSFT", "financials MSFT --json"],
+      examples: ["financials MSFT", "financials SAN:EPA", "financials MSFT --json"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "statements"),
   },
@@ -743,7 +1044,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["fundamentals <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["fundamentals NVDA"],
+      examples: ["fundamentals NVDA", "fundamentals ASML:AMS"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "fundamentals"),
   },
@@ -754,7 +1055,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["valuation <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["valuation NVDA"],
+      examples: ["valuation NVDA", "valuation BP:LSE"],
     },
     execute: (args, ctx) => runFinancials(args, ctx, "valuation"),
   },
@@ -764,7 +1065,8 @@ export const marketDataCliCommands: CliCommandDef[] = [
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["earnings <symbol...>"],
-      examples: ["earnings AAPL MSFT GOOGL"],
+      options: [EXCHANGE_OPTION],
+      examples: ["earnings AAPL MSFT GOOGL", "earnings SAN:EPA"],
     },
     execute: runEarnings,
   },
@@ -775,7 +1077,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["events <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["events KO"],
+      examples: ["events KO", "events BHP:ASX"],
     },
     execute: runEvents,
   },
@@ -786,18 +1088,22 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["analyst <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["analyst TSLA"],
+      examples: ["analyst TSLA", "analyst SAN:EPA"],
     },
     execute: runAnalyst,
   },
   {
     name: "holders",
-    description: "Fetch institutional, fund, and insider holders",
+    description: "Fetch institutional holders, or the 13D/13G beneficial owners",
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
-      usage: ["holders <symbol>"],
-      options: [EXCHANGE_OPTION],
-      examples: ["holders AAPL"],
+      usage: ["holders <symbol> [--form 13f|13d|13g|all] [--history]"],
+      options: [
+        { flags: "--form <form>", description: "13f for the holder table (default); 13d, 13g or all for beneficial owners over 5%" },
+        { flags: "--history", description: "With --form 13d, 13g or all, every report newest first instead of the latest per filer" },
+        EXCHANGE_OPTION,
+      ],
+      examples: ["holders AAPL", "holders SAN:EPA", "holders CAR --form all", "holders CAR --form 13g --history --json"],
     },
     execute: (args, ctx) => runHolders(args, ctx, "holders"),
   },
@@ -808,7 +1114,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
       group: CLI_COMMAND_GROUPS.companyData,
       usage: ["insider <symbol>"],
       options: [EXCHANGE_OPTION],
-      examples: ["insider NVDA"],
+      examples: ["insider NVDA", "insider BP:LSE"],
     },
     execute: (args, ctx) => runHolders(args, ctx, "insider", new Set(["insider", "direct"])),
   },
@@ -823,7 +1129,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
         title: "13F filings",
         lines: ["For each fund's reported position and its change over the quarter, run gloomberb fn 13F <symbol>."],
       }],
-      examples: ["13f AAPL"],
+      examples: ["13f AAPL", "13f BP:NYSE"],
     },
     execute: (args, ctx) => runHolders(args, ctx, "13f", new Set(["institution", "fund"])),
   },
@@ -832,12 +1138,13 @@ export const marketDataCliCommands: CliCommandDef[] = [
     description: "Fetch recent SEC filings",
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
-      usage: ["filings <symbol> [--count <n>]"],
+      usage: ["filings <symbol> [--count <n>] [--form <form>]"],
       options: [
         { flags: "--count <n>", description: "Number of filings (default 15)" },
+        { flags: "--form <form>", description: "Only this form and its amendments, such as 10-K or 13D" },
         EXCHANGE_OPTION,
       ],
-      examples: ["filings AAPL", "filings AAPL --count 40 --json"],
+      examples: ["filings AAPL", "filings BHP:ASX", "filings AAPL --count 40 --json", "filings CAR --form 13G"],
     },
     execute: runFilings,
   },
@@ -849,8 +1156,9 @@ export const marketDataCliCommands: CliCommandDef[] = [
       usage: ["news [symbol] [--feed <feed>]"],
       options: [
         { flags: "--feed <feed>", description: "latest, top, or breaking for market news (default latest)" },
+        EXCHANGE_OPTION,
       ],
-      examples: ["news", "news TSLA", "news --feed top --limit 10"],
+      examples: ["news", "news TSLA", "news SAN:EPA", "news --feed top --limit 10"],
     },
     execute: runNews,
   },