gloomberb 0.16.2 → 0.16.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",

package/src/brokers/account-cache.ts

@@ -1,4 +1,5 @@
 import type { AppResourceStorePort } from "../core/app-service-ports";
+import type { CachedResourceRecord, ResourceCacheKey } from "../data/resource-store";
 import type { BrokerAdapter } from "../types/broker";
 import type { BrokerInstanceConfig } from "../types/config";
 import type { CachePolicy } from "../types/persistence";
@@ -21,6 +22,50 @@ function brokerAccountNamespace(instance: BrokerInstanceConfig): string {
   return `plugin:${instance.brokerType}`;
 }
 
+/** A saved account snapshot, which a renderer without the cache database has to keep elsewhere. */
+export function isBrokerAccountSnapshotKey(key: Pick<ResourceCacheKey, "namespace" | "kind">): boolean {
+  return key.kind === BROKER_ACCOUNT_SNAPSHOT_KIND && key.namespace.startsWith("plugin:");
+}
+
+/**
+ * Saves an account snapshot written by a process without the cache database
+ * (the desktop view), keeping its own times. Anything else is refused.
+ */
+export function saveBrokerAccountRecord(
+  resources: Pick<AppResourceStorePort, "set">,
+  record: CachedResourceRecord | null | undefined,
+): boolean {
+  if (!record || typeof record.namespace !== "string" || typeof record.entityKey !== "string"
+    || !isBrokerAccountSnapshotKey(record)
+    || ![record.fetchedAt, record.staleAt, record.expiresAt].every(Number.isFinite)) return false;
+  resources.set(record, record.value, {
+    schemaVersion: record.schemaVersion,
+    provenance: record.provenance,
+    fetchedAt: record.fetchedAt,
+    cachePolicy: { staleMs: record.staleAt - record.fetchedAt, expireMs: record.expiresAt - record.fetchedAt },
+  });
+  return true;
+}
+
+export function deleteBrokerAccountRecord(resources: Pick<AppResourceStorePort, "delete">, key: ResourceCacheKey): void {
+  if (isBrokerAccountSnapshotKey(key)) resources.delete(key);
+}
+
+/** Every unexpired account snapshot saved for these profiles, as stored. */
+export function listPersistedBrokerAccountRecords(
+  resources: Pick<AppResourceStorePort, "list">,
+  brokerInstances: readonly BrokerInstanceConfig[],
+): CachedResourceRecord[] {
+  return brokerInstances.flatMap((instance) => resources.list<PersistedBrokerAccountSnapshot>({
+    namespace: brokerAccountNamespace(instance),
+    kind: BROKER_ACCOUNT_SNAPSHOT_KIND,
+    entityKey: instance.id,
+  }, {
+    schemaVersion: BROKER_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
+    touch: false,
+  }));
+}
+
 export function getBrokerAccountCacheSourceKey(
   instance: BrokerInstanceConfig,
   broker?: BrokerAdapter | null,

package/src/cli/command-options.ts

@@ -0,0 +1,74 @@
+import type { CliCommandDef } from "../types/plugin";
+import { fail } from "./errors";
+import { suggestCliOption } from "./help";
+
+/** A built-in command, which may say more about an option it does not take than the list of those it does. */
+export interface BuiltinCliCommandDef extends CliCommandDef {
+  /** A sentence for an unknown option people reach for, such as `--from` on `history`; null for the rest. */
+  unknownOptionHint?(flag: string): string | null;
+}
+
+interface DeclaredOption {
+  flag: string;
+  takesValue: boolean;
+}
+
+/** `--range`, `--range=5Y`: an option. `-5`, `---`, `--` and plain words are not. */
+const OPTION_TOKEN = /^--[a-z]/i;
+
+/**
+ * The options a command's help declares, from each spelling such as
+ * `--range <range>` (takes a value) or `--all` (a switch). Null when it takes
+ * any option: `--<option> <value>` on `fn` and `shot`.
+ */
+function declaredOptions(command: CliCommandDef): Map<string, DeclaredOption> | null {
+  const declared = new Map<string, DeclaredOption>();
+  for (const option of command.help?.options ?? []) {
+    for (const spelling of option.flags.split(",")) {
+      const trimmed = spelling.trim();
+      if (trimmed.startsWith("--<")) return null;
+      const match = /^(--?[a-z][\w-]*)(?:[ =](.+))?$/i.exec(trimmed);
+      if (match) declared.set(match[1]!, { flag: match[1]!, takesValue: match[2] != null });
+    }
+  }
+  return declared;
+}
+
+function failUnknownOption(command: BuiltinCliCommandDef, flag: string, declared: Map<string, DeclaredOption>): never {
+  const flags = [...declared.keys()];
+  const suggestion = suggestCliOption(flag, flags);
+  const help = `See gloomberb help ${command.name}.`;
+  fail(`Unknown option ${flag} for ${command.name}.`, [
+    command.unknownOptionHint?.(flag) ?? "",
+    suggestion ? `Did you mean ${suggestion}?` : "",
+    flags.length > 0 ? `Options: ${flags.join(", ")}. ${help}` : `${command.name} takes no options. ${help}`,
+  ].filter(Boolean).join("\n"));
+}
+
+/**
+ * Fails on the first `--option` a built-in command does not declare, which it
+ * would otherwise ignore and answer as if it had not been given: `history
+ * --from 1995-01-01` printing the default year. Global flags are already out
+ * of `args`; a declared option's value is skipped whatever it looks like, and
+ * nothing from `literalStart` on (after a bare `--`) is read as an option.
+ */
+export function checkCliCommandOptions(
+  command: BuiltinCliCommandDef,
+  args: readonly string[],
+  literalStart = args.length,
+): void {
+  const declared = declaredOptions(command);
+  if (!declared) return;
+  for (let index = 0; index < Math.min(literalStart, args.length); index += 1) {
+    const arg = args[index]!;
+    if (!OPTION_TOKEN.test(arg)) continue;
+    const equals = arg.indexOf("=");
+    const flag = equals >= 0 ? arg.slice(0, equals) : arg;
+    const option = declared.get(flag);
+    if (!option) failUnknownOption(command, flag, declared);
+    if (!option.takesValue && equals >= 0) {
+      fail(`${flag} takes no value.`, `Write it alone, as ${flag}. See gloomberb help ${command.name}.`);
+    }
+    if (option.takesValue && equals < 0) index += 1;
+  }
+}

package/src/cli/commands/command-utils.ts

@@ -46,6 +46,35 @@ export function requireArg(value: string | undefined, usage: string, ctx: CliCom
   return value;
 }
 
+/**
+ * Fails on arguments past the `max` a command takes rather than dropping them:
+ * `fx NGN ZAR` printing NGN alone reads as an answer for both. `usage` is the
+ * command's usage line without `gloomberb`, `takes` what it takes ("one
+ * currency", "no arguments").
+ */
+export function rejectExtraArgs(
+  args: readonly string[],
+  max: number,
+  { usage, takes, advice }: { usage: string; takes: string; advice?: string },
+  ctx: Pick<CliCommandContext, "fail">,
+): void {
+  if (args.length <= max) return;
+  const command = usage.split(" ")[0];
+  ctx.fail(`${command} takes ${takes}; got ${args.join(" ")}.`, [advice, `Usage: gloomberb ${usage}`].filter(Boolean).join("\n"));
+}
+
+/** The one argument a command takes, such as a symbol: missing fails with the usage line, extras are not dropped. */
+export function requireOneArg(
+  args: readonly string[],
+  usage: string,
+  noun: string,
+  ctx: CliCommandContext,
+): string {
+  const value = requireArg(args[0], `Usage: gloomberb ${usage}`, ctx);
+  rejectExtraArgs(args, 1, { usage, takes: `one ${noun}`, advice: `Run it once per ${noun}.` }, ctx);
+  return value;
+}
+
 export function isoDate(value: unknown): string {
   if (value instanceof Date) return value.toISOString();
   if (typeof value === "number") return new Date(value).toISOString();

package/src/cli/commands/market.ts

@@ -13,8 +13,9 @@ 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, 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,
@@ -33,10 +34,27 @@ import {
 } 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 { fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+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 {
@@ -65,11 +83,14 @@ import { nonUsSecListingVenue } from "../../utils/sec";
 import type { MarketContext } from "../types";
 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 {
@@ -250,6 +271,7 @@ function holderRows(data: HolderData, ownerTypes?: Set<string>) {
     value: holder.value ?? null,
     percentHeld: holder.percentHeld ?? null,
     changeShares: holder.changeShares ?? null,
+    shareBasis: holder.shareBasis ?? null,
   }));
 }
 
@@ -421,11 +443,16 @@ function failHistory(error: unknown, symbol: string, ctx: Parameters<CliCommandD
   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;
@@ -439,7 +466,11 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       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 +481,47 @@ 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("  ·  "))}`,
+      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,11 +529,33 @@ 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(
@@ -486,13 +569,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 +601,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,6 +616,7 @@ 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;
@@ -587,7 +677,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const count = parsePositiveInt(takeOption(args, "--count"), 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;
@@ -702,7 +792,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.");
@@ -724,16 +814,23 @@ async function runHolders(
     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 +847,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,7 +874,7 @@ 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([
@@ -807,7 +911,7 @@ 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([
@@ -837,7 +941,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const args = [...rawArgs];
   const expiration = takeOption(args, "--expiration");
   const exchangeOption = takeOption(args, "--exchange");
-  const raw = requireArg(args[0], "Usage: gloomberb options <symbol> [--expiration <unix>]", ctx);
+  const raw = requireOneArg(args, "options <symbol> [--expiration <unix>]", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const { symbol, exchange } = listing.request;
@@ -884,8 +988,10 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+const FX_USAGE = "fx <currency>";
+
 async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
-  const currency = requireArg(rawArgs[0]?.trim().toUpperCase(), "Usage: gloomberb fx <currency>", ctx);
+  const currency = requireOneArg(rawArgs.map((arg) => arg.trim().toUpperCase()), FX_USAGE, "currency", ctx);
   await withMarketData(ctx, async (market) => {
     const baseCurrency = market.config.baseCurrency.trim().toUpperCase();
     const load = (code: string) => market.dataProvider.getCachedQuery("getExchangeRate", [code])
@@ -948,7 +1054,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,13 +1082,23 @@ 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 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,
   },
   {
@@ -1032,8 +1148,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 +1159,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 +1170,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"),
   },
@@ -1167,7 +1283,7 @@ export const marketDataCliCommands: CliCommandDef[] = [
     description: "Convert a currency into your base currency",
     help: {
       group: CLI_COMMAND_GROUPS.markets,
-      usage: ["fx <currency>"],
+      usage: [FX_USAGE],
       examples: ["fx EUR", "fx JPY --json"],
     },
     execute: runFx,