gloomberb 0.18.1 → 0.18.3

package/src/cli/glossary.ts

@@ -2,7 +2,7 @@ import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText
 
 /**
  * Plain-words meanings of the rates, auction, credit and bond yield, energy, perpetual-futures, portfolio,
- * fund, bond fund (SEC yield, tax-equivalent yield, muni/Treasury ratio), short interest, quote-board, futures (basis, contango, roll yield), VIX curve (term structure, 3M/30D, VVIX) and economic-calendar terms the functions
+ * fund, bond fund (SEC yield, tax-equivalent yield, muni/Treasury ratio), short interest, quote-board, futures (basis, contango, roll yield), VIX curve (term structure, 3M/30D, VVIX), CFTC positioning (COT trader classes, net % of open interest) and economic-calendar terms the functions
  * show in their rows, headers and footers.
  * `catalog glossary` lists them, `catalog explain <term>` prints one, and
  * `fn <function> --explain` and `portfolio show --explain` follow a report with
@@ -242,7 +242,7 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "The first date the new rate level appears in the data, not necessarily the announcement or effective date.",
   },
   {
-    term: "Pctl 1Y", aliases: ["percentile", "1y percentile", "pctl"], functions: ["BTMM", "WIRP", "CBR", "CDX", "SOVR"],
+    term: "Pctl 1Y", aliases: ["percentile", "1y percentile", "1-year percentile", "pctl"], functions: ["BTMM", "WIRP", "CBR", "CDX", "SOVR", "COT"],
     definition: "Where today's value ranks against the past year of the same series: 100 is the highest, 0 the lowest.",
   },
   {
@@ -360,8 +360,8 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
       + "a simple annualisation of the rate now, not funding actually paid.",
   },
   {
-    term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP"],
-    definition: "The total value of contracts that are open and not yet closed, counting each buyer and seller pair once, usually in dollars. "
+    term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP", "COT"],
+    definition: "The contracts that are open and not yet closed, counting each buyer and seller pair once: COT counts them, PERP gives their value, usually in dollars. "
       + "It rises as new positions open and falls as they close.",
   },
   {
@@ -631,6 +631,59 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "A futures contract's official price for the day, set by its exchange from trading near the close. "
       + "The day's change and margin are measured from it, and it can differ from the last trade. FUT's PREV is the previous one.",
   },
+  // CFTC positioning (COT): the legacy report's trader classes, then the disaggregated report's.
+  {
+    term: "Commitments of Traders", short: "COT", aliases: ["cot report", "commitment of traders", "cftc", "cftc report", "cftc positioning", "positioning"],
+    functions: ["COT"], shown: ["CFTC", "COT"],
+    definition: "The CFTC's weekly count of who holds each US futures market: open contracts split by type of trader, as of Tuesday and published that Friday. "
+      + "It shows whether speculators or hedgers are net long or short, and how that moved since the week before.",
+  },
+  {
+    term: "Noncommercial", aliases: ["non-commercial", "noncommercials", "large speculators", "speculators", "large specs"], functions: ["COT"],
+    definition: "Large traders who do not hedge a business with the contract, such as funds and other speculators. "
+      + "Their net position is the one most often read as the market's bet.",
+  },
+  {
+    term: "Commercial", aliases: ["commercials", "hedgers", "commercial hedgers"], functions: ["COT"],
+    definition: "Large traders who use the contract to hedge a business: producers, processors, merchants and dealers. "
+      + "In a commodity they are usually net short, selling ahead what they will grow, mine or deliver.",
+  },
+  {
+    term: "Nonreportable", aliases: ["non-reportable", "nonreportables", "small traders", "small speculators"], functions: ["COT"],
+    definition: "Traders too small to report their positions to the CFTC, counted as open interest less every reported position. Mostly smaller speculators.",
+  },
+  {
+    term: "Net position", short: "Net", aliases: ["net long", "net short", "net positioning", "net spec"], functions: ["COT"], shown: ["Net"],
+    definition: "A group's long contracts less its short ones: positive is net long, negative net short.",
+  },
+  {
+    term: "Net % of open interest", short: "Net % OI", aliases: ["% of open interest", "percent of open interest", "net percent of open interest"], functions: ["COT"],
+    definition: "A group's net position as a share of all open contracts, so markets of different sizes compare: +8.3% means its longs exceed its shorts by 8.3% of open interest.",
+  },
+  {
+    term: "Weekly change", short: "1W Δ", aliases: ["1w change", "week change", "weekly net change"], functions: ["COT"],
+    definition: "How far a group's net position moved since the previous weekly report, in contracts.",
+  },
+  {
+    term: "Pctl 3Y", aliases: ["3y percentile", "3-year percentile", "three-year percentile"], functions: ["COT"],
+    definition: "Where this week's net position ranks against the past three years of weekly reports: 100 is the most net long it has been, 0 the most net short.",
+  },
+  {
+    term: "Managed money", aliases: ["money managers", "managed money traders", "hedge funds", "ctas"], functions: ["COT"], shown: ["Managed Money"],
+    definition: "The disaggregated report's funds that trade futures for clients, such as hedge funds and CTAs: the speculators most often watched.",
+  },
+  {
+    term: "Producer/merchant", aliases: ["producers", "merchants", "producer merchant", "processors"], functions: ["COT"], shown: ["Producer/Merchant"],
+    definition: "The disaggregated report's growers, miners, processors and merchants that hedge the physical commodity they produce or handle.",
+  },
+  {
+    term: "Swap dealers", aliases: ["swap dealer", "swaps dealers"], functions: ["COT"], shown: ["Swap Dealers"],
+    definition: "The disaggregated report's banks and dealers that hedge the commodity swaps they sell to clients, often index investors.",
+  },
+  {
+    term: "Other reportables", aliases: ["other reportable", "other reportable traders"], functions: ["COT"], shown: ["Other Reportables"],
+    definition: "The disaggregated report's large traders that fit none of its other classes, such as proprietary traders and family offices.",
+  },
   // Futures basis and curve shape (CTM, FUT, PERP).
   {
     term: "Futures basis", aliases: ["basis", "basis trade", "cash and carry", "cash-and-carry", "vs spot", "spot spread"],

package/src/cli/help.ts

@@ -58,7 +58,7 @@ const GLOBAL_OPTIONS: Array<[string, string]> = [
 
 const EXIT_CODES: Array<[string, string]> = [
   [String(CLI_EXIT_CODES.ok), "Success"],
-  [String(CLI_EXIT_CODES.error), "Failed: bad input, no data found or a failed check"],
+  [String(CLI_EXIT_CODES.error), "Failed: bad input, no data found or a failed check. fn exits 0 on partial data with warnings; --json ok is false exactly when this is 1"],
   [String(CLI_EXIT_CODES.unusableShot), "shot --strict saved an image of a pane with no usable data"],
 ];
 

package/src/cli/helpers.ts

@@ -1,10 +1,15 @@
 import {
   formatCompact,
   formatCurrency,
+  formatCurrencyCode,
   formatNumber,
   formatPercentRaw,
 } from "../utils/format";
-import { formatMarketPriceWithCurrency, type MarketFormatOptions } from "../market-data/market/format";
+import { formatMarketChangeWithCurrency, formatMarketPriceWithCurrency, type MarketFormatOptions } from "../market-data/market/format";
+import { changeBasisLabel, changeBasisNote, quoteChangeBasis } from "../market-data/market/change-basis";
+import type { FuturesContractTermsPayload } from "../api-client/futures-curve";
+import type { ActiveQuoteDisplay } from "../market-data/market/status";
+import type { Quote } from "../types/financials";
 import { cliStyles, colorBySign } from "../utils/cli-output";
 import type { AppConfig } from "../types/config";
 import type { Watchlist, TickerRecord } from "../types/ticker";
@@ -12,8 +17,36 @@ import { isFiniteNumber } from "../utils/guards";
 import { formatUtcTime } from "../utils/utc-time";
 import { findNamedCollection } from "../portfolio/collection-name";
 
-export function formatSignedCurrency(value: number, currency: string): string {
-  return value > 0 ? `+${formatCurrency(value, currency)}` : formatCurrency(value, currency);
+/** A signed amount with its sign ($), or with `code` its code (+12.50 CAD) as a report for another base currency writes it. */
+export function formatSignedCurrency(value: number, currency: string, code = false): string {
+  const text = (code ? formatCurrencyCode : formatCurrency)(value, currency);
+  return value > 0 ? `+${text}` : text;
+}
+
+/**
+ * The Change line of `ticker` and of `quote`'s futures block: the regular
+ * session's move and its percent, colored by sign, and what the move is
+ * measured from, "-HK$0.10 (-1.05%) vs Fri 16 Oct close" (a future's from
+ * its terms, "vs Fri 16 Oct settle"), with the venue's holidays since that
+ * close on the line under it ("HKEX closed Mon 19 Oct, holiday").
+ */
+export function quoteChangeText(
+  quote: Quote,
+  session: Pick<ActiveQuoteDisplay, "price" | "change" | "changePercent">,
+  options: MarketFormatOptions,
+  terms?: Pick<FuturesContractTermsPayload, "settlement" | "spec"> | null,
+  now = Date.now(),
+): string {
+  // A listing that no longer trades: its last close moves no more.
+  if (quote.delisting) return "—";
+  const move = colorBySign(
+    `${formatMarketChangeWithCurrency(session.change, quote.currency ?? "USD", options, session.price)} (${formatPercentRaw(session.changePercent)})`,
+    session.change,
+  );
+  const basis = quoteChangeBasis(quote, { terms });
+  if (!basis) return move;
+  const note = changeBasisNote(basis, now);
+  return `${move} ${cliStyles.muted(changeBasisLabel(basis, now))}${note ? `\n${cliStyles.muted(note)}` : ""}`;
 }
 
 // Text-table cell formats. They leave missing values blank; CSV and JSON keep the raw numbers.

package/src/cli/index.ts

@@ -47,6 +47,7 @@ import {
   runPaneScreenshot,
 } from "./pane-functions";
 import { catalogPointer, tickerPointer, type CatalogCommandHit } from "./unknown-command";
+import { exportCommandPointer } from "./known-gaps";
 import { catalogFredSeriesIds } from "./series-search";
 import { primeBoardCoins } from "./board-coins";
 
@@ -189,8 +190,16 @@ export function createCoreCliCommands(
           "fn WEI --csv --section europe > europe.csv",
           "fn 13F AAPL --view=ticker-holdings",
           "fn OVME --spot 100 --strike 100 --days 30 --volatility 25",
+          "fn HIVG SPY --event fomc --offset -6 --lookback ALL --csv",
           "fn AUCT --explain",
         ],
+        sections: [{
+          title: "Exit status",
+          lines: [
+            "0 when the report has data for what was asked, partial data with warnings about the rest included; 1 when it has none (an empty report, or rows with no value for a listing that has nothing) or the input is bad. --json ok is false exactly when the exit status is 1.",
+            "CSV headers are the same for every symbol: a reason a figure is missing goes to the status column, never into a number cell.",
+          ],
+        }],
       },
       execute: async (args, ctx) => {
         requirePaneFunctionTarget(args, "fn", ctx);
@@ -382,7 +391,9 @@ function failUnknownCommand(token: string, commands: CliCommandDef[], pointers:
       [`Run: ${pointers.nearFn.command}`, ticker].filter(Boolean).join("\n"),
     );
   }
-  const catalog = suggestion ? null : catalogPointer(token, pointers.hits, pointers.args);
+  // Exporting is a flag, not a command: `export LMT` says how, rather than listing functions that mention exports.
+  const exported = suggestion ? null : exportCommandPointer(token, pointers.args);
+  const catalog = suggestion ? null : exported ?? catalogPointer(token, pointers.hits, pointers.args);
   const help = suggestion
     ? `Did you mean ${suggestion}? Run gloomberb help to see every command.`
     : catalog ? `${catalog}\nRun gloomberb help to see every command.` : "Run gloomberb help to see every command.";

package/src/cli/issuer-membership.ts

@@ -0,0 +1,103 @@
+import type { AppConfig } from "../types/config";
+import type { DataProvider } from "../types/data-provider";
+import type { TickerRecord } from "../types/ticker";
+import { canonicalExchange, isUsListingExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { logFailure } from "../utils/log-failure";
+import { savedListingName } from "./listing-arg";
+
+/** A list holding the company: its name, and the other saved listing it holds the company as (null for the listing asked about). */
+export interface ListMembership {
+  name: string;
+  /** RCI.B:TSX when the list holds Rogers as its Toronto line and the report is of RCI. */
+  via: string | null;
+}
+
+export interface CompanyMemberships {
+  portfolios: ListMembership[];
+  watchlists: ListMembership[];
+}
+
+/**
+ * A listing as Gloom Cloud writes an issuer's listings: the bare ticker on a
+ * US venue or none (RCI), SYMBOL:EXCHANGE elsewhere (RCI.B:TSX), with a
+ * share class's dash or slash as a dot (BRK-B is BRK.B).
+ */
+export function issuerListingKey(symbol: string, exchange?: string): string {
+  const parsed = parsePublicTickerKey(symbol);
+  const venue = parsed.exchange ?? canonicalExchange(exchange);
+  const code = parsed.symbol.toUpperCase().replace(/[-/]/g, ".");
+  return venue && !isUsListingExchange(venue) ? `${code}:${venue}` : code;
+}
+
+function names(config: AppConfig, ids: readonly string[], kind: "portfolios" | "watchlists"): Map<string, string> {
+  const collections: ReadonlyArray<{ id: string; name: string }> = config[kind];
+  return new Map(ids.flatMap((id) => {
+    const name = collections.find((collection) => collection.id === id)?.name;
+    return name ? [[id, name] as const] : [];
+  }));
+}
+
+/**
+ * The portfolios and watchlists that hold a company, whichever of its
+ * listings they saved: the listing's own lists, then those holding another
+ * of `issuerListings` (its keys as `issuerListingKey` writes them), each
+ * once and saying which listing it holds. A restricted list holding RCI.B:TSX
+ * holds Rogers, which also trades as RCI in New York. Without the company's
+ * listings, only the listing's own lists.
+ */
+export function companyMemberships(
+  config: AppConfig,
+  own: TickerRecord | null,
+  saved: readonly TickerRecord[],
+  issuerListings: readonly string[] | null,
+): CompanyMemberships {
+  const listings = new Set(issuerListings ?? []);
+  const ownKey = own ? savedListingName(own).key : null;
+  const others = listings.size === 0 ? [] : saved.filter((ticker) =>
+    savedListingName(ticker).key !== ownKey
+    && listings.has(issuerListingKey(ticker.metadata.ticker, ticker.metadata.exchange)));
+  const collect = (kind: "portfolios" | "watchlists"): ListMembership[] => {
+    const held = new Map<string, ListMembership>();
+    for (const [id, name] of names(config, own?.metadata[kind] ?? [], kind)) held.set(id, { name, via: null });
+    for (const ticker of others) {
+      for (const [id, name] of names(config, ticker.metadata[kind], kind)) {
+        if (!held.has(id)) held.set(id, { name, via: savedListingName(ticker).key });
+      }
+    }
+    return [...held.values()];
+  };
+  return { portfolios: collect("portfolios"), watchlists: collect("watchlists") };
+}
+
+/**
+ * `companyMemberships` for a listing, asking Gloom Cloud for the company's
+ * other listings only when another saved listing is in a list at all. A
+ * failed lookup leaves the listing's own lists.
+ */
+export async function loadCompanyMemberships({
+  config,
+  own,
+  symbol,
+  exchange,
+  loadTickers,
+  dataProvider,
+}: {
+  config: AppConfig;
+  own: TickerRecord | null;
+  /** The listing the report is of, and its venue (RCI, NYSE). */
+  symbol: string;
+  exchange: string;
+  loadTickers: () => Promise<TickerRecord[]>;
+  dataProvider: Pick<DataProvider, "getIssuerListings">;
+}): Promise<CompanyMemberships> {
+  const ownKey = own ? savedListingName(own).key : null;
+  const saved = await Promise.resolve().then(loadTickers)
+    .catch(logFailure("cli.issuer-membership", "Reading saved listings failed", [] as TickerRecord[]));
+  const listed = saved.filter((ticker) => savedListingName(ticker).key !== ownKey
+    && (ticker.metadata.portfolios.length > 0 || ticker.metadata.watchlists.length > 0));
+  const { getIssuerListings } = dataProvider;
+  if (listed.length === 0 || !getIssuerListings) return companyMemberships(config, own, [], null);
+  const issuer = await Promise.resolve().then(() => getIssuerListings.call(dataProvider, symbol, exchange))
+    .catch(logFailure("cli.issuer-membership", "Reading the company's listings failed", null));
+  return companyMemberships(config, own, listed, issuer?.listings.map((listing) => issuerListingKey(listing.symbol, listing.exchange)) ?? null);
+}

package/src/cli/known-gaps.ts

@@ -109,6 +109,23 @@ const BANK_FIGURES_TOPIC = {
   closest: [["EQS", "NIM%, Pro: gloomberb fn EQS --metric kpiNimPercent"]],
 } as const;
 
+/**
+ * How to export: a flag on every command, which `export LMT`, `catalog export` and `catalog csv` look for as a
+ * command or a function. One example, writing a file.
+ */
+function exportLine(symbol = "LMT"): string {
+  return `Export: add --csv or --json to any command to print its result as CSV or JSON, e.g. gloomberb history ${symbol} --csv > ${
+    symbol.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.csv`;
+}
+
+const EXPORT_POINTER = {
+  names: ["export", "exporting", "csv", "json", "excel", "spreadsheet", "xlsx"],
+  words: ["data", "to", "as", "a", "an", "the", "in", "into", "file", "files", "table", "tables", "result", "results", "output",
+    "format", "save", "how", "can", "i", "my", "report", "reports", "command", "commands"],
+  line: exportLine(),
+  leads: true,
+} as const;
+
 /** "bank", "bank figures": beside the functions a bank's name finds (CBR), where its figures are. */
 const BANK_FIGURES_POINTER = {
   names: ["bank", "banks", "banking"],
@@ -193,8 +210,9 @@ export function topicPointer(query: string): { message: string; codes: string[]
  * "dark pool"; "drip", "dividend income", but not "income statement" or "net income"; "tether", "depeg",
  * "usdc peg", but not "peg ratio".
  */
-const COMMAND_POINTERS: ReadonlyArray<{ names: readonly string[]; words: readonly string[]; line: string }> = [
+const COMMAND_POINTERS: ReadonlyArray<{ names: readonly string[]; words: readonly string[]; line: string; leads?: true }> = [
   BANK_FIGURES_POINTER,
+  EXPORT_POINTER,
   {
     names: ["theme", "themes", "light", "dark", "colorblind", "colourblind", "blind"],
     words: ["mode", "color", "colour", "colors", "colours", "high", "contrast", "change", "switch", "set", "setting", "settings"],
@@ -218,6 +236,24 @@ export function commandPointer(query: string): string | null {
   return findCommandPointer(query)?.line ?? null;
 }
 
+/**
+ * Whether the query's command line answers it ahead of the functions its words find: "csv" is the flag, not
+ * CDS, whose description happens to mention it.
+ */
+export function commandPointerLeads(query: string): boolean {
+  return findCommandPointer(query)?.leads === true;
+}
+
+/**
+ * The line for a command word typed as `gloomberb export LMT`: exporting is a flag every command takes, not a
+ * command, so the example runs on the symbol typed. Null for any other word.
+ */
+export function exportCommandPointer(token: string, args: readonly string[]): string | null {
+  if (findCommandPointer(token) !== EXPORT_POINTER) return null;
+  const symbol = args.find((arg) => /^\^?[A-Z0-9][A-Z0-9.=-]{0,11}(?::[A-Z0-9]{1,8})?$/.test(arg) && /[A-Z]/.test(arg));
+  return exportLine(symbol);
+}
+
 function findCommandPointer(query: string): (typeof COMMAND_POINTERS)[number] | null {
   const asked = words(query);
   if (asked.length === 0) return null;

package/src/cli/listing-arg.ts

@@ -42,6 +42,7 @@ import { classifyInstrumentType, kindFromListingSyntax } from "../tickers/instru
 import type { InstrumentOfKind } from "../tickers/instrument-coverage";
 import { brokerIndexCode, brokerIndexReadAs } from "./index-roots";
 import { readTerminalListingCode, terminalCodeReadAs } from "../tickers/terminal-codes";
+import { listingAbroadVenue } from "../utils/sec";
 
 /** The `--exchange` option of every command that takes a ticker. */
 export const EXCHANGE_OPTION = {
@@ -342,7 +343,7 @@ export function listingChoiceNote(
 }
 
 // Quotes of these never name a company's listing, so they are never a choice between companies.
-const UNLISTED_TYPES = new Set(["FUTURE", "INDEX", "CURRENCY", "CRYPTOCURRENCY", "OPTION"]);
+export const UNLISTED_TYPES = new Set(["FUTURE", "INDEX", "CURRENCY", "CRYPTOCURRENCY", "OPTION"]);
 
 /** Whether the data service chose the listing: a bare symbol, with no venue named and none saved. */
 function isBareListing(listing: Pick<CliListing, "exchange" | "saved">): boolean {
@@ -835,6 +836,13 @@ export async function loadSavedListing(store: ListingStore, listing: ListingArg)
   return null;
 }
 
+/** A row saved under a vendor's suffixed key (RY.TO) for the listing it was read as: on that venue, or on none it names. */
+async function loadSuffixedRow(store: ListingStore, key: string, exchange: string): Promise<TickerRecord | null> {
+  const ticker = await store.loadTicker(key);
+  const savedExchange = canonicalExchange(ticker?.metadata.exchange);
+  return ticker && (!savedExchange || savedExchange === exchange) ? ticker : null;
+}
+
 export interface CliListing extends ListingArg {
   saved: TickerRecord | null;
   /**
@@ -860,11 +868,47 @@ async function builderDexMarket(listing: ListingArg, deps: ListingDeps): Promise
     : null;
 }
 
+/** A symbol written with a venue's suffix, as data vendors write a listing abroad: RY.TO, 7203.T, VOD.L, 0700.HK. */
+const VENUE_SUFFIX = /^([A-Z0-9][A-Z0-9&-]*)\.([A-Z]{1,3})$/;
+
+/**
+ * RY.TO, 7203.T, VOD.L: a listing abroad written with a data vendor's venue
+ * suffix, read as the listing its own quote names (RY:TSX, 7203:JPX,
+ * VOD:LSE), the way `quote` names it, so data that is read by venue (a
+ * company's SEC filings, data that covers US listings only) finds the same
+ * listing the quote is for. A US share class (BRK.B, quoted on NYSE), a
+ * suffix no quote answers and a named venue stay as typed.
+ */
+async function readVenueSuffix(listing: ListingArg, deps: Pick<ListingDeps, "dataProvider">): Promise<ListingArg | null> {
+  const match = listing.exchange ? null : VENUE_SUFFIX.exec(listing.symbol);
+  if (!match) return null;
+  let quote: Quote | null;
+  try {
+    quote = await deps.dataProvider.getQuote(listing.symbol, "");
+  } catch (error) {
+    // The command's own request then says what is wrong with the symbol.
+    if (!isNoProviderError(error)) logFailure("cli.listing-arg", "Quote venue suffix failed")(error);
+    return null;
+  }
+  const venue = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
+  const key = `${match[1]}:${venue}`;
+  if (!venue || !isKnownExchangeCode(venue) || !listingAbroadVenue(key)) return null;
+  return { symbol: match[1]!, exchange: venue, key, readAs: `Read ${listing.symbol} as ${key}.` };
+}
+
 export async function resolveCliListing(
   raw: string,
   exchangeOption: string | null | undefined,
   deps: ListingDeps,
-  options: { ownExchangeWins?: boolean } = {},
+  options: {
+    ownExchangeWins?: boolean;
+    /**
+     * Read a venue suffix (RY.TO) as the listing its quote names (RY:TSX).
+     * Only pane functions ask for it (`applyListingArgument`, which `fn` and
+     * `shot` run through), as their data is read by venue.
+     */
+    venueSuffix?: boolean;
+  } = {},
 ): Promise<CliListing> {
   // "JPM US Equity" is Bloomberg's code for JPM; "Putnam US Equity", whose root is no US ticker, is a name.
   const typed = stripStrayEdges(raw).text || raw;
@@ -879,6 +923,10 @@ export async function resolveCliListing(
   // USD-NGN and USDNGN are the pair USDNGN=X unless a security is listed under those letters.
   const pair = parsed.exchange ? null : await readAmbiguousCurrencyPair(parsed.symbol, deps);
   if (pair) parsed = { symbol: pair, exchange: "", key: pair };
+  const suffixed = pair || named || !options.venueSuffix ? null : await readVenueSuffix(parsed, deps);
+  // The row may be saved under the suffixed key itself: a link or a layout's key is kept as it came.
+  const typedKey = suffixed ? parsed.symbol : null;
+  if (suffixed) parsed = parsed.readAs ? { ...suffixed, readAs: `${parsed.readAs} ${suffixed.readAs}` } : suffixed;
   try {
     await checkListingExchange(parsed, deps);
   } catch (error) {
@@ -887,7 +935,7 @@ export async function resolveCliListing(
     parsed = market;
   }
   let listing = await settleSharedCode(parsed, deps);
-  const saved = await loadSavedListing(deps.store, listing);
+  const saved = await loadSavedListing(deps.store, listing) ?? (typedKey ? await loadSuffixedRow(deps.store, typedKey, listing.exchange) : null);
   // A code nothing could read stays the venue it is saved on.
   const savedExchange = canonicalExchange(saved?.metadata.exchange);
   if (listing.sharedCode && savedExchange) listing = { symbol: listing.symbol, exchange: savedExchange, key: `${listing.symbol}:${savedExchange}` };

package/src/cli/name-entries.ts

@@ -6,26 +6,65 @@ import { splitSymbolWords } from "./symbol-args";
 import { isProviderBusy } from "../sources/provider-errors";
 
 /**
- * The entries of a list (`splitSymbolArgs`) as the symbols a command
- * resolves. An entry with a space in it is a company's name when search finds
- * the company (`Whirlpool Corporation`), and stays whole for its listing to
- * say what it was read as; otherwise it is its words, each a symbol, as a
- * pasted line always was (`brk.b bf-b`). Only those entries cost a search.
- * One search was too busy to look up also stays whole, so its lookup says so
- * instead of resolving its words as symbols of other companies.
+ * The entries of a list (`splitSymbolArgs`, or a file's lines) as the symbols
+ * a command resolves. An entry with a space in it is a company's name when
+ * search finds the company (`Whirlpool Corporation`, `philip morris intl`),
+ * and stays whole for its listing to say what it was read as. One search
+ * finds no company for is its words, each a symbol, when each is written as
+ * a symbol or has a quote (`AAPL MSFT`, `brk.b bf-b`, `aapl msft` on a
+ * pasted line), and otherwise stays whole, a name nothing lists: its words
+ * are not taken for other companies' symbols (INTL, a fund, from a misspelt
+ * `phillip morris intl`). Only those entries cost a search. One search was
+ * too busy to look up also stays whole, so its lookup says so instead of
+ * resolving its words as symbols of other companies.
  */
 export async function readNameEntries(
   entries: readonly string[],
-  dataProvider: Pick<DataProvider, "search">,
+  dataProvider: Pick<DataProvider, "search"> & Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
 ): Promise<string[]> {
-  const read = await Promise.all(entries.map(async (entry) => (
+  const read = await Promise.all(entries.map(async (entry) => {
     // A terminal's code for a listing ("JPM US Equity") is one entry, like a company's name.
-    await readTerminalCodeArg(dataProvider, entry) || (isCompanyNameInput(entry) && await findListingOfCompanyName(dataProvider, entry).catch(busyAsFound))
-      ? [entry] : splitSymbolWords([entry])
-  )));
+    if (await readTerminalCodeArg(dataProvider, entry)) return [entry];
+    if (!isCompanyNameInput(entry)) return splitSymbolWords([entry]);
+    if (await findListingOfCompanyName(dataProvider, entry).catch(busyAsFound)) return [entry];
+    const words = splitSymbolWords([entry]);
+    return await wordsAreSymbols(words, dataProvider) ? words : [entry];
+  }));
   return read.flat();
 }
 
+/** A word typed as a ticker is: in capitals (AAPL, 7203.T), with a venue or class mark (brk.b, bf-b, SAN:EPA), or after a $. */
+function writtenAsSymbol(word: string): boolean {
+  return /^\$|[:.\-/=^]/.test(word) || /\d/.test(word) || (/\p{Lu}/u.test(word) && !/\p{Ll}/u.test(word));
+}
+
+/**
+ * Whether the words of an entry search found no company for are symbols:
+ * each written as one (2222, BRK.B) or else with a quote, the others asked in
+ * one batch (`2222 amd pltr`). A batch that fails says nothing, and the
+ * entry stays a name.
+ */
+async function wordsAreSymbols(
+  words: readonly string[],
+  dataProvider: Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
+): Promise<boolean> {
+  const symbols = words.filter((word) => !writtenAsSymbol(word)).map((word) => word.replace(/^\$/, "").toUpperCase());
+  if (symbols.length === 0) return true;
+  if (dataProvider.getQuotesBatch) {
+    const results = await dataProvider.getQuotesBatch(symbols.map((symbol) => ({ symbol, exchange: "" })))
+      .catch(logFailure("cli.name-entries", "Read quotes for a pasted line failed", []));
+    return results.length === symbols.length && results.every(({ quote }) => !!quote);
+  }
+  // A source without batches is asked a quote at a time: the few words not written as symbols.
+  const { getQuote } = dataProvider;
+  if (!getQuote) return false;
+  const quoted = await Promise.all(symbols.map((symbol) => getQuote(symbol, "").then(
+    (quote) => !!quote,
+    logFailure("cli.name-entries", "Read a quote for a pasted line failed", false),
+  )));
+  return quoted.every(Boolean);
+}
+
 /** `findListingOfCompanyName`'s busy answer as a name to keep whole, any other failure as it is. */
 function busyAsFound(error: unknown): true {
   if (isProviderBusy(error)) return true;

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

@@ -18,6 +18,8 @@ export interface PaneFunctionCapability {
   botSafe: boolean;
   tickerCardinality: PaneFunctionTickerCardinality;
   aliases: string[];
+  /** Words that are no code but ask for this function's data: `fn` and `catalog` answer them with it. */
+  suggestFor?: string[];
   intents: string[];
   outputKind: string;
   reportReadiness: PaneFunctionReadiness;

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

@@ -210,6 +210,21 @@ export function nearFunctionCodes(
     .sort((left, right) => left.code.localeCompare(right.code));
 }
 
+/**
+ * The functions a word that is no code asks for (`IVOL`, `IV`: HIVG and
+ * OVDV), as their `discovery.suggestFor` lists it, each by its code.
+ */
+export function suggestedFunctionCodes(registry: PaneFunctionCatalog, name: string): NearFunctionCode[] {
+  const wanted = normalizeLookupToken(name);
+  if (!wanted) return [];
+  return [...registry.paneTemplates.values()].flatMap((template) => {
+    const pane = registry.panes.get(template.paneId);
+    const words = pane ? getHeadlessPaneDefinition(template, pane)?.discovery?.suggestFor ?? [] : [];
+    const code = template.shortcut?.prefix;
+    return code && words.some((word) => normalizeLookupToken(word) === wanted) ? [{ code: code.toUpperCase(), label: template.label }] : [];
+  }).sort((left, right) => left.code.localeCompare(right.code));
+}
+
 function sampleArgForTemplate(template: PaneTemplateDef): string {
   switch (template.shortcut?.argKind) {
     case "ticker":
@@ -391,6 +406,7 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
     entry.token,
     entry.shortcut,
     ...entry.aliases,
+    ...entry.capability.suggestFor ?? [],
     entry.templateId,
     entry.paneId,
   ].filter((value): value is string => !!value).map((value) => normalizeLookupToken(value));
@@ -694,13 +710,15 @@ export function renderPaneCatalogReport(
   series: readonly SeriesMatch[] = [],
   /** The `config` command a query names a setting of ("light theme"), printed last, beside the functions. */
   setting: string | null = null,
+  /** The setting answers the query ahead of the functions its words find (`csv` is the flag, not CDS): printed first. */
+  settingFirst = false,
 ): string {
   const query = args.query.trim().toLowerCase();
   const exact = query
     ? entries.find((entry) => entry.token.toLowerCase() === query)
       ?? entries.find((entry) => entry.aliases.some((alias) => alias.toLowerCase() === query))
     : undefined;
-  const withSetting = (text: string) => [text, setting ?? ""].filter(Boolean).join("\n\n");
+  const withSetting = (text: string) => (settingFirst ? [setting ?? "", text] : [text, setting ?? ""]).filter(Boolean).join("\n\n");
   if (exact) return withSetting([renderCatalogEntry(exact), renderAlsoMatches(exact, entries, query)].filter(Boolean).join("\n\n"));
 
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);