gloomberb 0.16.6 → 0.17.0

package/src/cli/pane-functions/dom.ts

@@ -1,5 +1,5 @@
 import type { DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
-import { cliStyles, renderSection, renderTable } from "../../utils/cli-output";
+import { cliStyles, cliTerminalWidth, renderSection, renderTable, wrapText } from "../../utils/cli-output";
 import { formatUtcTime } from "../../utils/utc-time";
 import type { MarketContext } from "../types";
 import type { PaneFunctionReport } from "./report";
@@ -14,6 +14,8 @@ const DOM_REPORT_WIDTH = 1280;
 const DOM_REPORT_HEIGHT = 720;
 const DOM_LIMITATION =
   "Only values visible in the rendered pane are returned; clipped or off-screen data may be omitted.";
+/** The widest a lock note wraps to, as the catalog's text. */
+const LOCK_NOTE_WIDTH = 100;
 const DOM_EVERY_ROW =
   "Every row of the pane's table is returned, including rows scrolled out of view.";
 
@@ -119,7 +121,7 @@ function renderDomTables(rows: DesktopPaneShotRenderedRow[]): string[] {
 function domReportTables(
   rows: DesktopPaneShotRenderedRow[],
   title: string,
-  freshness: ReportFreshness,
+  freshness: ReportFreshness | null,
   incomplete: boolean | string,
   notices: readonly string[],
 ): CliReportTables {
@@ -130,7 +132,7 @@ function domReportTables(
       table.columns.map((column) => column.header),
       table.rows.map((cells) => table.columns.map((column) => cells.get(column.key))),
     )),
-    footer: reportFooterLines({ freshness, incomplete, notes: notices }),
+    footer: reportFooterLines({ ...(freshness ? { freshness } : {}), incomplete, notes: notices }),
   };
 }
 
@@ -190,10 +192,19 @@ export function buildDomPaneReportFromRender(
   const rendered = renderedReportNotices(result.render.semanticUi ?? []);
   const notices = [...(resolved.pane.reportNotices?.(resolved.instance.settings ?? {}) ?? []), ...rendered.notices];
   const textLines = [resolved.label, "", ...notices, ...(notices.length > 0 ? [""] : [])];
+  // A wall in place of the whole pane: nothing was read, so the report says
+  // what is locked and how to reach it, and cites no source.
+  const gate = !hasStructuredRows ? result.render.accessGate ?? null : null;
+  const lockNote = gate ? resolved.pane.reportLockNote?.({ gate, symbol: result.symbols[0] ?? null }) ?? null : null;
+  const locked = gate === "sign-in" || lockNote ? gate : null;
+  // JSON and CSV say why the report is empty in the note's words, on one line.
+  const lockReason = lockNote?.replace(/\s*\n\s*/g, " ") ?? null;
   if (hasStructuredRows) {
     textLines.push(...renderDomTables(rows));
+  } else if (lockNote) {
+    textLines.push(...wrapText(lockNote, Math.min(cliTerminalWidth() ?? LOCK_NOTE_WIDTH, LOCK_NOTE_WIDTH)));
   } else if (result.render.visibleText) {
-    textLines.push(result.render.accessGate === "sign-in" ? signInWallText(result.render.visibleText) : result.render.visibleText);
+    textLines.push(gate === "sign-in" ? signInWallText(result.render.visibleText) : result.render.visibleText);
   } else {
     textLines.push(failureReason ?? "No rendered values were available.");
   }
@@ -226,45 +237,49 @@ export function buildDomPaneReportFromRender(
       truncationReasons,
       ...(everyRow ? { everyRow } : {}),
       limitation: everyRow ? DOM_EVERY_ROW : DOM_LIMITATION,
-      ...(failureReason ? { reason: failureReason } : {}),
+      ...(lockReason ?? failureReason ? { reason: lockReason ?? failureReason } : {}),
       ...(notices.length > 0 ? { metadata: { ...rendered.facts, notices } } : {}),
-      freshness,
+      ...(locked ? { locked } : { freshness }),
     },
     text: textLines.join("\n").trimEnd(),
     tables: domReportTables(
       rows,
       resolved.label,
-      freshness,
-      !complete && (failureReason ?? (truncationReasons.length > 0 ? truncationReasons.join("; ") : true)),
+      locked ? null : freshness,
+      !complete && (lockReason ?? failureReason ?? (truncationReasons.length > 0 ? truncationReasons.join("; ") : true)),
       notices,
     ),
   };
 }
 
+/** The report's closing lines; a locked view, which read nothing, cites no source. */
 export function appendDomReportFooter(
   text: string,
   elapsedMs: number,
   view: DomReportView,
-  freshness: ReportFreshness,
+  freshness: ReportFreshness | undefined,
 ): string {
   return [
     text,
     "",
     domReportNote(elapsedMs, view),
-    cliStyles.muted(formatFreshnessLine(freshness)),
+    ...(freshness ? [cliStyles.muted(formatFreshnessLine(freshness))] : []),
   ].join("\n");
 }
 
-/** How much of the pane a rendered-view report holds: cut, every row its tables publish, or what the viewport shows. */
-export type DomReportView = "clipped" | "every-row" | "visible";
+/** How much of the pane a rendered-view report holds: none behind a wall, cut, every row its tables publish, or what the viewport shows. */
+export type DomReportView = "locked" | "clipped" | "every-row" | "visible";
 
 export function domReportView(data: Readonly<Record<string, unknown>>): DomReportView {
+  if (data.locked) return "locked";
   return data.truncated === true ? "clipped" : data.everyRow === true ? "every-row" : "visible";
 }
 
 /** What a rendered-view report says about where its values come from. */
 export function domReportNote(elapsedMs: number, view: DomReportView): string {
-  const source = view === "every-row"
+  const source = view === "locked"
+    ? "Rendered view: the pane is locked, so no values were read."
+    : view === "every-row"
     ? "Rendered view: every row of the pane's table, including rows scrolled out of view."
     : `Rendered view: values come from the visible pane. ${view === "clipped" ? "The rendered view is clipped." : "The rendered view may be clipped."}`;
   return `${source} Render time: ${elapsedMs} ms.`;

package/src/cli/pane-functions/function-help.ts

@@ -225,7 +225,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["RV"],
   },
   EQS: {
-    summary: "Screen covered stocks on valuation, growth, margins, liquidity, short interest, insider activity and 13F holders, then rank the matches by any metric.",
+    summary: "Screen covered stocks on valuation, growth, margins, liquidity, volatility, short interest, insider activity and 13F holders, then rank the matches by any metric. "
+      + "ATR% is the 14-session average true range as a percent of the last close. IV rank is a rank, not an IV percentile: 0 is the lowest 30-day implied volatility of the past 52 weeks and 100 the highest.",
     usage: ["EQS"],
     keys: [key("a", "dd criterion"), key("m", "etric"), key("s", "ave screen"), key("o", "pen research")],
     data: same("Daily snapshot, statements as filed"),
@@ -717,7 +718,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["RRG"],
   },
   HM: {
-    summary: "The largest US stocks and ETFs as a treemap sized by the square root of market cap or assets, or by plain market cap in its settings, and colored by the day's move.",
+    summary: "The largest US stocks and ETFs as a treemap sized by the day's move, or by market cap or its square root (assets for ETFs) in its settings, and colored by the day's move.",
     usage: ["HM"],
     keys: [OPEN],
     data: QUOTES,
@@ -780,6 +781,22 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: same("Weekly, on release"),
     bloomberg: ["DOE"],
   },
+  PSD: {
+    summary: "World production, use, trade and ending stocks for wheat, corn, soybeans and cotton, by country and latest market year. Season-average price forecasts appear when USDA publishes them. The Crops tab of Commodities & Energy.",
+    usage: ["PSD"],
+    keys: [TABS],
+    data: same("Monthly, as USDA updates the market-year tables"),
+    bloomberg: [],
+    docs: "https://gloom.sh/docs/functions",
+  },
+  JODI: {
+    summary: "Latest monthly crude oil and natural gas balances for countries: production, imports, exports and stocks, and demand for natural gas. The Oil & Gas tab of Commodities & Energy.",
+    usage: ["JODI"],
+    keys: [TABS],
+    data: same("Monthly, as the latest country reports arrive"),
+    bloomberg: [],
+    docs: "https://gloom.sh/docs/functions",
+  },
   POWER: {
     summary: "Pro: global power interconnection queues, recorded MW history, completion and withdrawal cohorts, large-load requests and approvals, utility exposure and generation capacity. Open a project for primary evidence and revisions; mapped companies link to DES, FA, G and SPLC.",
     usage: ["POWER", "POWER NEE"],
@@ -797,10 +814,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   EPWR: {
-    summary: "Day-ahead power prices for 32 European markets in EUR/MWh, and the EU carbon allowance (EUA) auction price in EUR/tCO2. Each market shows its latest delivery day, the change on the day before, 7- and 30-day averages, a year ago and where it sits in its 52-week range, with its year charted and its history from 2015; the EUA shows its latest auction day, how the auction was covered, and its auctions since 2020. The Prices tab of POWER.",
-    usage: ["EPWR", "EPWR DE", "EPWR UK", "EPWR EUA"],
-    keys: [key("o", "pen Ember"), key("g", "raph"), key("c", "arbon")],
-    data: same("Daily; each market as of its latest published delivery day, usually a few days back; the EUA on each auction day"),
+    summary: "Day-ahead power prices for 32 European markets in EUR/MWh, the EU carbon allowance (EUA) auction price in EUR/tCO2, and European gas storage. Each market shows its latest delivery day, the change on the day before, 7- and 30-day averages, a year ago and where it sits in its 52-week range, with its year charted and its history from 2015; the EUA shows its latest auction day, how the auction was covered, and its auctions since 2020. EPWR GAS shows the EU and each member state's storage as of its latest gas day: % full, TWh, injection and withdrawal in GWh/day, against a year ago and the five-year range, with the year charted against last year and that range. The Prices tab of POWER.",
+    usage: ["EPWR", "EPWR DE", "EPWR UK", "EPWR EUA", "EPWR GAS", "EPWR GAS DE"],
+    keys: [key("o", "pen Ember or GIE AGSI+"), key("g", "raph"), key("c", "arbon")],
+    data: same("Daily; each market as of its latest published delivery day, usually a few days back; the EUA on each auction day; gas storage by gas day, published each evening, the latest day estimated until confirmed"),
     bloomberg: [],
     docs: "POWER",
   },
@@ -927,6 +944,34 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: same("Daily, after each auction"),
     bloomberg: ["AUCT"],
   },
+  FI: {
+    summary: "A single workspace for credit markets, issuer debt, corporate bonds, Treasury auctions and debt, and primary dealer positions.",
+    usage: ["FI"],
+    keys: [TABS],
+    data: same("As each market publishes"),
+    bloomberg: [],
+  },
+  TRACE: {
+    summary: "Recent corporate and agency bond sales with issuer, coupon, price, yield, and grade. Add an issuer to narrow the tape.",
+    usage: ["TRACE", "TRACE Ford"],
+    keys: [SEARCH],
+    data: same("As trades are published"),
+    bloomberg: [],
+  },
+  DTS: {
+    summary: "US Treasury daily operating cash and debt held by the public, with recent business days for debt.",
+    usage: ["DTS"],
+    keys: [TABS],
+    data: same("Daily, as Treasury publishes"),
+    bloomberg: [],
+  },
+  PDLR: {
+    summary: "Weekly primary dealer net positions and settlement fails across Treasuries and mortgage-backed securities.",
+    usage: ["PDLR"],
+    keys: [TABS],
+    data: same("Weekly, as published"),
+    bloomberg: [],
+  },
   BTMM: {
     summary: "Funding rates (SOFR, EFFR, IORB), Treasury bill yields and their curve, and Fed liquidity from reserves to the reverse repo, each with its one-year percentile.",
     usage: ["BTMM"],

package/src/cli/pane-functions/headless.ts

@@ -31,7 +31,7 @@ import {
   type CliReportTable,
   type CliReportTables,
 } from "../report-tables";
-import { labelWithUnit } from "../../utils/display-number";
+import type { ExportIdentity } from "../export-source";
 import { observationDate } from "../../time-series/price-comparison";
 import type { ResolvedSeries } from "../../time-series/types";
 import type { PaneFunctionReport } from "./report";
@@ -268,6 +268,7 @@ export function serializeHeadlessPaneResult(
   const common = {
     ...(result.errors ? { errors: result.errors } : {}),
     ...(result.notes?.length ? { notes: result.notes } : {}),
+    ...(result.warnings?.length ? { warnings: result.warnings } : {}),
     ...(result.metadata ? { metadata: result.metadata } : {}),
   };
   switch (definition.shape) {
@@ -478,17 +479,22 @@ function displayedColumns(columns: HeadlessPaneColumn[]): HeadlessPaneColumn[] {
 
 const SERIES_FIELDS = ["value", "open", "high", "low", "close", "volume"] as const;
 
-/** Every point of a series: its date (the trading date for session bars) and its values, in the series' unit. */
+/**
+ * Every point of a series: its date (the trading date for session bars) and
+ * its values, in the series' unit, which the export's `currency_or_unit`
+ * column names beside the bare `Value`, `Open`... headers.
+ */
 function seriesTable(series: HeadlessSeries): CliReportTable {
   const fields = SERIES_FIELDS.filter((field) => series.points.some((point) => point[field] != null));
-  const unit = series.unit?.trim() ?? "";
   const dates = series.points.map((point) => seriesPointExportDate(series, point.date));
-  const header = (field: (typeof SERIES_FIELDS)[number]) => {
-    const name = `${field[0]!.toUpperCase()}${field.slice(1)}`;
-    return field === "volume" ? name : labelWithUnit(name, unit);
-  };
+  const header = (field: (typeof SERIES_FIELDS)[number]) => `${field[0]!.toUpperCase()}${field.slice(1)}`;
   return {
     title: series.label,
+    identity: {
+      ...(series.symbol?.trim() ? { symbolOrSeries: series.symbol.trim() } : {}),
+      ...(series.unit?.trim() ? { currencyOrUnit: series.unit.trim() } : {}),
+      ...(series.interval?.trim() ? { interval: series.interval.trim() } : {}),
+    },
     columns: [dates.every((date) => date.length <= 10) ? "Date" : "Time", ...fields.map(header)],
     rows: series.points.map((point, index) => [
       dates[index]!,
@@ -576,6 +582,7 @@ export function headlessReportTables(
   const { locked, failed } = splitErrors(result);
   return {
     tables,
+    identity: reportIdentity(definition, result, args),
     footer: reportFooterLines({
       freshness,
       incomplete: incompleteDetail(result, status),
@@ -586,6 +593,18 @@ export function headlessReportTables(
   };
 }
 
+/**
+ * What a report's exported rows are of when it is about one symbol or series:
+ * the one a chart's series were asked as, else the one symbol asked for or
+ * resolved. A series table names its own symbol, unit and interval.
+ */
+function reportIdentity(definition: HeadlessPaneDefinition, result: HeadlessPaneResult, args: HeadlessPaneLoadArgs): ExportIdentity {
+  const series = definition.shape === "series" ? (result as HeadlessSeriesResult).series : [];
+  const charted = [...new Set(series.flatMap((entry) => entry.symbol?.trim() ? [entry.symbol.trim()] : []))];
+  const symbols = charted.length > 0 ? charted : args.symbols.length > 0 ? args.symbols : result.symbols ?? [];
+  return symbols.length === 1 ? { symbolOrSeries: symbols[0]! } : {};
+}
+
 function reportTitle(
   definition: HeadlessPaneDefinition,
   args: HeadlessPaneLoadArgs,

package/src/cli/pane-functions/index.ts

@@ -10,7 +10,7 @@ import {
   type PaneFunctionCatalog,
 } from "./catalog";
 import { createPaneCatalog } from "./discovery";
-import { findCatalogSeries } from "../series-search";
+import { catalogFredSeriesIds, findCatalogSeries } from "../series-search";
 import {
   parsePaneCatalogArgs,
   parsePaneFunctionArgs,
@@ -106,12 +106,17 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
           `${resolved.token} did not produce a complete bot-safe report.${unavailable}`,
         );
       }
+      // A chart or other series exported to CSV or NDJSON with no rows fails, rather than writing a header alone.
+      if (tabular && report.data.kind === "series" && report.data.empty) {
+        const empty = emptySeriesExport(resolved.token, parsed.arg, report.data, catalogFredSeriesIds(ctx.plugins), `--${ctx.cliOptions.format}`);
+        ctx.fail(empty.message, empty.details);
+      }
       // --explain follows the report with the terms it shows; JSON lists them under `glossary`.
       const glossary = parsed.explain ? reportGlossary(resolved.token, report.text) : null;
       const data = glossary
         ? { ...report.data, glossary: glossary.map(({ term, short, definition }) => ({ term, ...(short ? { short } : {}), definition })) }
         : report.data;
-      const warnings = [...parsed.listingNotes ?? [], ...await choice ?? []];
+      const warnings = [...parsed.listingNotes ?? [], ...await choice ?? [], ...report.data.warnings ?? []];
       // The report states its own freshness in its data and text; JSON cites it as `source` too.
       ctx.printResult({ data, exportFreshness: report.data.freshness, ...(warnings.length > 0 ? { warnings } : {}) }, {
         text: () => glossary ? `${report.text}\n\n${renderReportGlossary(resolved.token, glossary)}` : report.text,
@@ -121,6 +126,41 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
   });
 }
 
+/**
+ * What a series export that came back with no rows says: what was asked, why
+ * when the report knows, and what to run instead. A FRED series ID given where
+ * a ticker goes (`fn G DEXSFUS`) is charted with the `fred:` prefix.
+ */
+export function emptySeriesExport(
+  token: string,
+  arg: string,
+  data: { unavailableSymbols: readonly string[]; errors?: readonly string[] },
+  fredSeriesIds: ReadonlySet<string>,
+  formatFlag = "--csv",
+): { message: string; details: string } {
+  const asked = ["fn", token, arg.trim()].filter(Boolean).join(" ");
+  const fred = data.unavailableSymbols
+    .map((symbol) => symbol.split(":")[0]!.trim().toUpperCase())
+    .filter((id) => /^[A-Z0-9]+$/.test(id) && fredSeriesIds.has(id));
+  if (fred.length > 0) {
+    const ids = [...new Set(fred)];
+    return {
+      message: `${asked} has no data to export: ${ids.join(" and ")} ${ids.length === 1 ? "is a FRED series" : "are FRED series"}, not ${ids.length === 1 ? "a ticker" : "tickers"}.`,
+      details: `Chart it with the fred: prefix: gloomberb fn G ${ids.map((id) => `fred:${id}`).join(",")} ${formatFlag}`
+        + `${ids.length === 1 ? ` (or gloomberb fred ${ids[0]} ${formatFlag})` : ""}.`,
+    };
+  }
+  const missing = data.unavailableSymbols.length > 0 ? ` for ${data.unavailableSymbols.join(", ")}` : "";
+  const reasons = (data.errors ?? []).map((error) => error.replace(/^[a-z0-9-]+-\d+: /, ""));
+  return {
+    message: `${asked} has no data to export${missing}.`,
+    details: [
+      ...reasons,
+      `Check the symbol with gloomberb search, or run gloomberb ${asked} without ${formatFlag} to see the report.`,
+    ].join("\n"),
+  };
+}
+
 /** How long a capture's process may stay up after its output, for a report it stopped waiting for. */
 const STALLED_REPORT_EXIT_MS = 1_000;
 
@@ -263,7 +303,10 @@ async function runPaneCliCommand(ctx: CliCommandContext, run: () => Promise<void
     // A listing it cannot use says what to type instead; a name that opens nothing, what is close to it.
     if (error instanceof ListingArgError || error instanceof UnknownPaneFunctionError) ctx.fail(error.message, error.details);
     const message = error instanceof Error ? error.message : String(error);
-    ctx.fail(message);
+    // A failure the command already worded keeps its advice line.
+    const stated = error instanceof Error ? (error as Error & { details?: unknown }).details : undefined;
+    const details = typeof stated === "string" ? stated : undefined;
+    ctx.fail(message, details);
   }
 }
 

package/src/cli/pane-functions/report-notices.ts

@@ -41,7 +41,9 @@ function publishedSources(value: unknown): NonNullable<HeadlessPaneFreshness["so
 /**
  * How current a rendered pane says its data is, from the `report-freshness`
  * node it publishes: `{ asOf?, status?, delayMinutes?, source?, sources?,
- * maxAgeMinutes?, oldestAge?, note? }`. A capture keeps no footer status and
+ * maxAgeMinutes?, oldestAge?, note?, basis? }`; `basis` names what a pane
+ * that is not a feed lists, when one pane lists different things (NI's
+ * stories, and its LTR code's letters). A capture keeps no footer status and
  * few cells carry a time, so a pane that knows its feed (OMON's chain) dates
  * the report here, as the plain command over the same data does, and a pane
  * over several venues (PERP) dates each one as its report does. A pane whose
@@ -50,10 +52,10 @@ function publishedSources(value: unknown): NonNullable<HeadlessPaneFreshness["so
  */
 export function renderedReportFreshness(
   semanticUi: readonly RemoteUiNodeSnapshot[],
-): Pick<HeadlessPaneFreshness, "asOf" | "status" | "delayMinutes" | "source" | "sources" | "maxAgeMinutes" | "oldestAge" | "note"> {
+): Pick<HeadlessPaneFreshness, "asOf" | "status" | "delayMinutes" | "source" | "sources" | "maxAgeMinutes" | "oldestAge" | "note" | "basis"> {
   const metadata = semanticUi.find((node) => node.role === "report-freshness")?.metadata;
   if (!metadata) return {};
-  const { asOf, status, delayMinutes, source, maxAgeMinutes, oldestAge, note } = metadata as Record<string, unknown>;
+  const { asOf, status, delayMinutes, source, maxAgeMinutes, oldestAge, note, basis } = metadata as Record<string, unknown>;
   const sources = publishedSources(metadata.sources);
   return {
     ...(typeof asOf === "string" || isFiniteNumber(asOf) ? { asOf } : {}),
@@ -64,6 +66,7 @@ export function renderedReportFreshness(
     ...(isFiniteNumber(maxAgeMinutes) && maxAgeMinutes > 0 ? { maxAgeMinutes } : {}),
     ...(oldestAge === true ? { oldestAge } : {}),
     ...(typeof note === "string" && note.trim() ? { note } : {}),
+    ...(typeof basis === "string" && basis.trim() ? { basis } : {}),
   };
 }
 

package/src/cli/pane-functions/report.ts

@@ -22,8 +22,18 @@ interface PaneFunctionReportData {
   empty: boolean;
   complete: boolean;
   unavailableSymbols: string[];
-  /** Source, as-of in UTC and live/delayed/stale/not-a-feed status; the last line of the text report. */
-  freshness: ReportFreshness;
+  /** Report errors: a source that did not answer, a symbol that is not one. */
+  errors?: string[];
+  /** What the report could not do as asked and did instead; `fn` prints them on stderr and in JSON's `warnings`. */
+  warnings?: string[];
+  /**
+   * Source, as-of in UTC and live/delayed/stale/not-a-feed status; the last
+   * line of the text report. Absent when a wall covered the pane (`locked`),
+   * since nothing was read.
+   */
+  freshness?: ReportFreshness;
+  /** The wall that covered the whole pane, so the report read nothing. */
+  locked?: "sign-in" | "pro";
   [key: string]: unknown;
 }
 
@@ -72,6 +82,10 @@ export async function buildFunctionReport(
     : await buildDomFunctionReport(resolved, context, rawArg);
   const elapsedMs = Math.max(0, Math.round(performance.now() - startedAt));
   report.data = { ...report.data, source, elapsedMs };
+  // A report about one symbol names it on every exported row; a chart's series name their own.
+  if (!report.tables.identity && report.data.symbols.length === 1) {
+    report.tables = { ...report.tables, identity: { symbolOrSeries: report.data.symbols[0]! } };
+  }
   if (source === "dom") {
     const view = domReportView(report.data);
     report.text = appendDomReportFooter(report.text, elapsedMs, view, report.data.freshness);

package/src/cli/pane-functions/resolver.ts

@@ -143,14 +143,16 @@ export async function applyListingArgument(
   const abroad = usOnly ? listings.filter((listing) => listingAbroadVenue(listing.key) != null) : [];
   if (usOnly && abroad.length > 0) {
     const token = found.template?.shortcut?.prefix ?? args.target.toUpperCase();
-    const answers = await Promise.all(abroad.map((listing) => usListingsOnlyMessage(
-      usOnly, listing, context, (key) => `gloomberb ${command} ${token} ${key}`,
-    )));
+    const answers = await Promise.all(abroad.map(async (listing) => {
+      const answer = await usListingsOnlyMessage(usOnly, listing, context, (key) => `gloomberb ${command} ${token} ${key}`);
+      const hint = headless?.usListingsOnlyHint?.(listing.key);
+      return hint ? { ...answer, details: `${answer.details}\n${hint}` } : answer;
+    }));
     listings = listings.filter((listing) => !abroad.includes(listing));
     if (listings.length === 0) {
       throw new ListingArgError(answers.map((answer) => answer.message).join("\n"), answers.map((answer) => answer.details).join("\n"));
     }
-    notes.push(...answers.map((answer) => `${answer.message} ${answer.details}`));
+    notes.push(...answers.map((answer) => `${answer.message} ${answer.details.replaceAll("\n", " ")}`));
   }
   // One listing's notes come with its choice note; a list's are said here.
   if (listings.length > 1) notes.unshift(...listings.flatMap(listingReadNotes));
@@ -233,6 +235,7 @@ export async function resolvePaneFunction(
   const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
     strict: args.requireBotSafe || (!!headless && resolutionSettings.strictHeadlessOptions === true),
     code: token,
+    argument: args.arg || null,
   });
   const settings = {
     ...optionSettings(args.options),

package/src/cli/report-tables.ts

@@ -17,7 +17,12 @@ import {
 } from "../utils/display-number";
 import { isEpochMilliseconds, parseReportTime } from "../utils/utc-time";
 import type { ReportFreshness } from "./pane-functions/freshness";
-import { exportSourceLines } from "./export-source";
+import {
+  EXPORT_IDENTITY_COLUMNS,
+  exportIdentityCells,
+  exportSourceLines,
+  type ExportIdentity,
+} from "./export-source";
 
 type CliReportValue = string | number;
 
@@ -29,12 +34,16 @@ export interface CliReportTable {
   columns: string[];
   /** Numbers, ISO times and text; an empty string for a missing value. */
   rows: CliReportValue[][];
+  /** What this table's rows are of, where it differs from the report's: one series of a chart. */
+  identity?: ExportIdentity;
 }
 
 export interface CliReportTables {
   tables: CliReportTable[];
   /** What CSV writes after the data as `#` lines: source and as-of, completeness, errors, notes. */
   footer: string[];
+  /** What the rows are of, for the fixed columns every row ends with (`EXPORT_IDENTITY_COLUMNS`). */
+  identity?: ExportIdentity;
 }
 
 /** A column as a report declares it: the text view draws `format(value, row)`, or the value itself. */
@@ -443,14 +452,25 @@ function csvLine(row: readonly unknown[]): string {
   return `"${first}"${line.slice(first.length)}`;
 }
 
+/**
+ * A table with the fixed columns after its own, every row naming what it is
+ * and the source and as-of the footer cites. A table without columns stays empty.
+ */
+function identifiedTable(table: CliReportTable, report: CliReportTables, freshness: ReportFreshness | undefined): CliReportTable {
+  if (!freshness || table.columns.length === 0) return table;
+  const cells = exportIdentityCells(freshness, { ...report.identity, ...table.identity });
+  return { ...table, columns: [...table.columns, ...EXPORT_IDENTITY_COLUMNS], rows: table.rows.map((row) => [...row, ...cells]) };
+}
+
 /**
  * One table writes as a plain CSV; several write as blocks, each under a
  * `# section: <title>` line, with a blank line between. The footer follows
- * the data as `#` lines after a blank line.
+ * the data as `#` lines after a blank line. With the `freshness` the footer
+ * cites, every row ends with the fixed columns of `EXPORT_IDENTITY_COLUMNS`.
  */
-export function renderReportCsv(report: CliReportTables): string {
+export function renderReportCsv(report: CliReportTables, freshness?: ReportFreshness): string {
   const marked = report.tables.length > 1;
-  const blocks = report.tables.map((table) => [
+  const blocks = report.tables.map((table) => identifiedTable(table, report, freshness)).map((table) => [
     ...(marked ? [commentLine(`section: ${table.title}`)] : []),
     ...(table.columns.length > 0 ? [[table.columns, ...table.rows].map(csvLine).join("\n")] : []),
   ].join("\n"));
@@ -462,10 +482,14 @@ export function withCsvFooter(csv: string, footer: readonly string[]): string {
   return [csv, footer.map(commentLine).join("\n")].filter(Boolean).join("\n\n");
 }
 
-/** One JSON object per row, keyed by column; rows of a report with several tables name their section. */
-export function renderReportNdjson(report: CliReportTables): string {
+/**
+ * One JSON object per row, keyed by column; rows of a report with several
+ * tables name their section. With the report's `freshness`, every row ends
+ * with the fixed fields CSV ends it with.
+ */
+export function renderReportNdjson(report: CliReportTables, freshness?: ReportFreshness): string {
   const tagged = report.tables.length > 1;
-  return report.tables.flatMap((table) => {
+  return report.tables.map((table) => identifiedTable(table, report, freshness)).flatMap((table) => {
     const sectionKey = table.columns.some((column) => column.toLowerCase() === "section") ? "_section" : "section";
     return table.rows.map((row) => {
       const object: Record<string, CliReportValue | null> = tagged ? { [sectionKey]: table.title } : {};

package/src/cli/result.ts

@@ -16,7 +16,15 @@ import { formatUtcTime, isEpochMilliseconds, isZonedIsoDateTime } from "../utils
 import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
 import { withSearchHints, type FredSeriesCheck } from "./not-a-ticker";
 import { renderReportCsv, renderReportNdjson, withCsvFooter, type CliReportTables } from "./report-tables";
-import { exportSource, exportSourceLines, type ExportSource } from "./export-source";
+import {
+  EXPORT_IDENTITY_COLUMNS,
+  exportIdentityCells,
+  exportIdentityFields,
+  exportSource,
+  exportSourceLines,
+  type ExportIdentity,
+  type ExportSource,
+} from "./export-source";
 import { windowRows, type RowWindow, type RowWindowOptions } from "./row-window";
 
 export interface CliResult<T = unknown> {
@@ -28,7 +36,8 @@ export interface CliResult<T = unknown> {
    * (docs/usage.md#how-current-a-report-is): the last line of the text output
    * and `metadata.freshness` in JSON. Exports cite it too (`exportSource`):
    * CSV ends with it as `#` lines, or `tables` footer does, and JSON carries
-   * it as `source`. NDJSON stays rows only.
+   * it as `source`. NDJSON stays rows only. CSV and NDJSON rows end with the
+   * fixed columns of `EXPORT_IDENTITY_COLUMNS`, its source and as-of among them.
    */
   freshness?: ReportFreshness;
   /**
@@ -88,6 +97,15 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
    * text view shows them, CSV with its `# section:` and closing `#` lines.
    */
   tables?: CliReportTables;
+  /**
+   * What the rows are of, for the fixed columns (`EXPORT_IDENTITY_COLUMNS`)
+   * CSV and NDJSON end every row with when the result cites a source: one
+   * identity for every row, or each row's own. Without it a row's own
+   * `symbol` and `currency` fields say it, as far as they go.
+   */
+  exportIdentity?: ExportIdentity | ((row: Row) => ExportIdentity);
+  /** What CSV says after the source lines as `# note:` lines: what the rows do not show, such as where a series begins. */
+  exportNotes?: readonly string[];
 }
 
 interface CliResultJsonEnvelope<T> extends Omit<CliResult<T>, "freshness" | "exportFreshness"> {
@@ -267,18 +285,34 @@ function serializeColumns<Row>(columns?: CliResultColumn<Row>[]) {
 function renderCsv<Row extends Record<string, unknown>>(
   rows: Row[],
   columns?: CliResultColumn<Row>[],
+  identity?: (row: Row) => string[],
 ): string {
   const resolvedColumns = columns && columns.length > 0
     ? columns
     : inferColumns(rows as Record<string, unknown>[]) as CliResultColumn<Row>[];
   return serializeCsv([
-    resolvedColumns.map((column) => column.header),
-    ...rows.map((row) => resolvedColumns.map((column) => (
-      column.value ? column.value(row) : row[column.key]
-    ))),
+    [...resolvedColumns.map((column) => column.header), ...identity ? EXPORT_IDENTITY_COLUMNS : []],
+    ...rows.map((row) => [
+      ...resolvedColumns.map((column) => (column.value ? column.value(row) : row[column.key])),
+      ...identity?.(row) ?? [],
+    ]),
   ]);
 }
 
+function stringField(row: Record<string, unknown>, key: string): string | null {
+  const value = row?.[key];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+/** What a row is of: as the command says, else its own `symbol` and `currency` fields. */
+function rowIdentity<Row extends Record<string, unknown>>(
+  row: Row,
+  declared: CliResultRenderOptions<unknown, Row>["exportIdentity"],
+): ExportIdentity {
+  if (typeof declared === "function") return declared(row);
+  return declared ?? { symbolOrSeries: stringField(row, "symbol"), currencyOrUnit: stringField(row, "currency") };
+}
+
 function textColumns<Row extends Record<string, unknown>>(
   rows: Row[],
   columns?: CliResultColumn<Row>[],
@@ -389,16 +423,25 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
   renderOptions: CliResultRenderOptions<T, Row>,
   cited?: ReportFreshness,
 ): string {
-  if (renderOptions.tables && options.format === "csv") return renderReportCsv(renderOptions.tables);
-  if (renderOptions.tables && options.format === "ndjson") return renderReportNdjson(renderOptions.tables);
+  if (renderOptions.tables && (options.format === "csv" || options.format === "ndjson")) {
+    // A report's tables name what they are of, else the command's one identity for every row does.
+    const declared = renderOptions.exportIdentity;
+    const tables = renderOptions.tables.identity || !declared || typeof declared === "function"
+      ? renderOptions.tables
+      : { ...renderOptions.tables, identity: declared };
+    return options.format === "csv" ? renderReportCsv(tables, cited) : renderReportNdjson(tables, cited);
+  }
   const window = windowed(asRows(result.data, renderOptions.rows), options, renderOptions);
   const rows = window.rows;
   if (options.format === "ndjson") {
-    return rows.map((row) => JSON.stringify(row)).join("\n");
+    return rows.map((row) => JSON.stringify(cited && isPlainObject(row)
+      ? { ...row, ...exportIdentityFields(cited, rowIdentity(row as Row, renderOptions.exportIdentity)) }
+      : row)).join("\n");
   }
   if (options.format === "csv") {
-    const csv = renderCsv(rows as Row[], renderOptions.columns);
-    return cited ? withCsvFooter(csv, exportSourceLines(cited)) : csv;
+    if (!cited) return renderCsv(rows as Row[], renderOptions.columns);
+    const csv = renderCsv(rows as Row[], renderOptions.columns, (row) => exportIdentityCells(cited, rowIdentity(row, renderOptions.exportIdentity)));
+    return withCsvFooter(csv, [...exportSourceLines(cited), ...(renderOptions.exportNotes ?? []).map((note) => `note: ${note}`)]);
   }
   if (renderOptions.text) {
     return renderOptions.text(result.data);