gloomberb 0.17.4 → 0.17.6

package/src/cli/commands/ticker.ts

@@ -27,7 +27,8 @@ import {
   getExtendedSessionDisplay,
   getQuoteSessionFields,
   getRegularSessionDisplay,
-  marketStateLabel,
+  quoteHeadlineTime,
+  quoteMarketStateLabel,
 } from "../../market-data/market/status";
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { futuresContractLines, futuresSettleText, isFuturesInstrument, loadFuturesContractTerms } from "../../market-data/futures-contract";
@@ -59,8 +60,10 @@ import { NotesFiles } from "../../plugins/builtin/notes/files";
 import { isKnownNonUsListing } from "../../utils/sec";
 import { canonicalExchange, exchangeLabel, isKnownExchangeCode, isUsListingExchange } from "../../utils/exchanges";
 import {
-  failIfNotTraded, ListingArgError, listingChoiceNotes, listingIdentity, loadBareVenues, resolveCliListing, type CliListing,
+  failIfNotTraded, failMovedSymbol, ListingArgError, listingChoiceNotes, listingFateLoader, listingIdentity, loadBareVenues,
+  resolveCliListing, type CliListing, type ListingDataRequest,
 } from "../listing-arg";
+import { movedAwayChange } from "../../tickers/ticker-changes";
 import { isNotATickerMessage } from "../not-a-ticker";
 import { sharesOutstandingInReceipts } from "../../utils/depositary-receipt";
 import { cliFreshnessFooter } from "../result";
@@ -714,7 +717,7 @@ export async function buildTickerReport({
     listingVenueLabel(listingExchange, quote, financials, tickerFile) || undefined,
     (quote?.currency || financials.quoteMetadata?.currency || tickerFile?.metadata.currency)
       ? `Currency ${quote?.currency || financials.quoteMetadata?.currency || tickerFile?.metadata.currency}` : undefined,
-    quote?.marketState ? marketStateLabel(quote.marketState) : undefined,
+    quoteMarketStateLabel(quote) ?? undefined,
     quote?.dataSource ? `Source ${quote.dataSource.toUpperCase()}` : undefined,
   ].filter((part): part is string => !!part);
   if (summaryParts.length > 0) {
@@ -795,7 +798,7 @@ export async function buildTickerReport({
       // A perpetual's price comes with no volume; its 0 means not reported, not no trades.
       ["Volume", quote.volume != null && !(quote.volume === 0 && isCryptoVenuePerpetual(quote.instrumentType, quote.name))
         ? formatNumber(quote.volume, 0) : "—"],
-      ["Updated", formatTimestamp(quote.lastUpdated)],
+      ["Updated", formatTimestamp(quoteHeadlineTime(quote))],
     ]);
 
     if (futuresContract) appendMetricSection(lines, "Contract", futuresContractMetrics(futuresContract, quote.symbol ?? symbol));
@@ -989,6 +992,17 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     const toBase = createBaseConverter(dataProvider, config.baseCurrency);
     // A bare symbol's venues load beside its research, to name the company it was read as when several list it.
     const venues = loadBareVenues(listing, { store, dataProvider });
+    // So does what became of the symbol, read from the research's quote as `history` reads it: a
+    // company that moved (HFC became DINO), with nothing new listed there, has no profile of its own.
+    const researchQuote = Promise.withResolvers<Quote | null>();
+    const fate = listingFateLoader(listing, { dataProvider }, researchQuote.promise);
+    const request: ListingDataRequest = { command: "ticker", noun: "research", fate };
+    /** Nothing to show: a company that moved is under its new symbol. */
+    const failIfMovedAway = async () => {
+      researchQuote.resolve(null);
+      const moved = movedAwayChange((await fate()).change);
+      if (moved) failMovedSymbol(moved, request);
+    };
 
     let financials: TickerFinancials | null = null;
     try {
@@ -996,6 +1010,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     } catch (error) {
       // A known exchange the symbol is not listed on: say where it is.
       await failIfNotTraded(listing, { store, dataProvider }, { fail: failCommand });
+      await failIfMovedAway();
       const reason = error instanceof Error ? error.message : String(error);
       // A symbol no listing carries is not a failed fetch, and the message already names it.
       if (isNotATickerMessage(reason)) failCommand(reason);
@@ -1016,10 +1031,15 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     );
     if (!financials || (!hasResearchData && !tickerFile?.metadata.positions.some((position) => position.shares !== 0))) {
       await failIfNotTraded(listing, { store, dataProvider }, { fail: failCommand });
+      await failIfMovedAway();
       failCommand(`No research data available for ${normalized}.`);
     }
     const resolvedFinancials = financials as TickerFinancials;
     const quote = resolvedFinancials.quote;
+    // The quote is the old line's (stopped, or named for the company that left): the profile and figures are another security's.
+    researchQuote.resolve(quote ?? null);
+    const { moved } = await fate();
+    if (moved) failMovedSymbol(moved, request);
 
     const notesFiles = new NotesFiles(dataDir);
     const listingName = listingIdentity(listing, quote).name;

package/src/cli/context.ts

@@ -13,7 +13,9 @@ import { getLoadablePlugins } from "../plugins/catalog";
 import { standaloneSeriesInvoker } from "../series/standalone";
 import type { PluginRegistry } from "../plugins/registry";
 import type { LoadedExternalPlugin } from "../plugins/loader";
+import { apiClient } from "../api-client";
 import { fail } from "./errors";
+import { resolvePersistedCloudSessionToken } from "./pane-functions/cloud-session";
 import type { ConfigContext, MarketContext } from "./types";
 
 export { withCliServices, withConfigData, withMarketData } from "./scoped-context";
@@ -105,8 +107,18 @@ export async function initConfigData(): Promise<ConfigContext> {
   return { config, persistence, store, dataDir };
 }
 
+/**
+ * Market commands (`quote`, `compare`, `history`...) run with the session the
+ * app saved after sign-in, as `fn` does: Gloom Cloud answers a Pro account
+ * with real-time quotes and anyone else with delayed ones.
+ */
+function applyPersistedCloudSession(context: Pick<MarketContext, "persistence">): void {
+  apiClient.setSessionToken(resolvePersistedCloudSessionToken(context));
+}
+
 export async function initMarketData(options: CliContextOptions = {}): Promise<MarketContext> {
   const context = await initConfigData();
+  applyPersistedCloudSession(context);
   const plugins = options.plugins ?? getLoadablePlugins();
   const capabilities = resolveCliCapabilities(context.config, plugins);
   const dataProvider = new AssetDataRouter(null, [], context.persistence.resources);
@@ -131,6 +143,7 @@ export async function initCliServices(options: CliServicesOptions = {}) {
   services.providerRouter.setConfigAccessor(() => config);
   services.providerRouter.setBackgroundRevalidation(false);
   await ensureCliServicesReady(services);
+  applyPersistedCloudSession(services);
   return {
     config,
     dataDir,

package/src/cli/errors.ts

@@ -22,13 +22,16 @@ class CliFailure extends Error {
   readonly code: string;
   readonly details?: unknown;
   readonly retryable?: boolean;
+  /** What a structured format carries beside the message; text prints the message alone. */
+  readonly fields?: Record<string, unknown>;
 
-  constructor(message: string, details?: unknown, code = CLI_ERROR_CODE, retryable?: boolean) {
+  constructor(message: string, details?: unknown, code = CLI_ERROR_CODE, retryable?: boolean, fields?: Record<string, unknown>) {
     super(message);
     this.name = "CliFailure";
     this.code = code;
     this.details = details;
     this.retryable = retryable;
+    this.fields = fields;
   }
 }
 
@@ -36,12 +39,21 @@ export function fail(message: string, details?: unknown, code?: string): never {
   throw new CliFailure(message, details, code);
 }
 
+/**
+ * Fails with its own code and the fields `--json` reads beside the message:
+ * `{ ok: false, error: { code, message, ...fields } }`. Text prints the
+ * message alone, and the exit status is any failure's.
+ */
+export function failWithFields(message: string, code: string, fields: Record<string, unknown>): never {
+  throw new CliFailure(message, undefined, code, undefined, fields);
+}
+
 export function closeAndFail(persistence: AppPersistence, message: string, details?: string): never {
   persistence.close();
   fail(message, details);
 }
 
-function isCliFailure(error: unknown): error is CliFailure {
+export function isCliFailure(error: unknown): error is CliFailure {
   return error instanceof CliFailure;
 }
 
@@ -57,6 +69,7 @@ function cliErrorObject(error: unknown): CliErrorObject {
       message: error.message,
       details: error.details,
       retryable: error.retryable,
+      ...error.fields,
     };
   }
   // Gloom Cloud refused what was asked (an unknown series, a bad date): the input was wrong, not the program.

package/src/cli/fx-pair.ts

@@ -1,3 +1,6 @@
+import { currencyMinorDigits } from "../market-data/market/format";
+import { parseTypedNumber, readCurrencyAmount } from "../utils/decimal-comma";
+
 /**
  * What `gloomberb fx` is asked for. A bare code is one unit of it in the base
  * currency (`NGN`: USD per 1 NGN). A pair is market convention, BASE/QUOTE:
@@ -42,6 +45,80 @@ export function parseFxRequest(raw: string, baseCurrency: string): FxRequest | {
     : { currency: parts[0]!, baseCurrency: baseCurrency.trim().toUpperCase() };
 }
 
+/** What `gloomberb fx` is asked for, with the amount to convert when one comes first. */
+export interface FxArgs {
+  request: FxRequest;
+  /** The amount of `currency` to convert into `baseCurrency`; absent for a rate alone. */
+  amount?: number;
+  /** One currency after an amount names no target, so it converts to USD; the answer says so. */
+  toUsdByDefault?: boolean;
+}
+
+/** Every form `fx` takes, for its usage line. */
+export const FX_USAGE = "fx <currency> | fx <base>/<quote> | fx <amount> <from>/<to> | fx <amount> <from> <to>";
+
+/**
+ * `fx` arguments: a currency or a pair (`EUR`, `USD/NGN`), or an amount and
+ * what to convert it from and to (`1234.5 EUR/USD`, `1234,5 EUR USD`). The
+ * amount is an amount of the first currency and reads as cash does
+ * (`readCurrencyAmount`): `1.234,5` and `1,234.5` are 1234.5, and `1,234` or
+ * `1.234` are thousands unless that currency has three decimals, where they are
+ * refused naming both readings. An amount and one currency converts to USD
+ * (`toUsdByDefault`). The error sentence otherwise.
+ */
+export function parseFxArgs(args: readonly string[], baseCurrency: string): FxArgs | { error: string } {
+  if (args.length === 1) {
+    const request = parseFxRequest(args[0]!, baseCurrency);
+    if (!("error" in request)) return { request };
+    // A lone number is an amount with nothing to convert it from.
+    return parseTypedNumber(args[0]).kind === "invalid"
+      ? request
+      : { error: `fx ${args[0]!.trim()} names no currency; convert an amount as fx ${args[0]!.trim()} EUR/USD.` };
+  }
+  if (args.length === 0 || args.length > 3) {
+    return { error: `fx takes a currency, a pair, or an amount and a pair (fx 1234.5 EUR/USD); got ${args.length} arguments.` };
+  }
+  const typed = args.map((arg) => arg.trim());
+  const [first, ...codes] = typed;
+  if (parseTypedNumber(first).kind === "invalid") {
+    // The amount typed after the pair (fx EUR/USD 100) belongs in front.
+    if (parseTypedNumber(typed.at(-1)).kind === "number") {
+      return { error: `Put the amount first: fx ${[typed.at(-1), ...typed.slice(0, -1)].join(" ")}.` };
+    }
+    // Two codes are one pair (fx NGN ZAR is NGN/ZAR), never two answers.
+    const pair = typed.length === 2 && typed.every((arg) => /^[A-Za-z]{3}$/.test(arg)) ? typed.join("/").toUpperCase() : "EUR/USD";
+    return { error: `fx takes one currency or pair; got ${typed.join(" ")}. Write a pair as ${pair}, or convert an amount as fx 1234.5 ${pair}.` };
+  }
+  const toUsdByDefault = codes.length === 1 && !codes[0]!.includes("/");
+  const request = parseFxRequest(codes.join("/"), "USD");
+  if ("error" in request) return request;
+  // The amount is in the currency converted from, so its units say what 1,234 means.
+  let amount: number;
+  try {
+    amount = readCurrencyAmount(first, "The amount", request.currency);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  return { request, amount, ...(toUsdByDefault ? { toUsdByDefault } : {}) };
+}
+
+/**
+ * An amount in its currency's minor units, grouped (1,234.50 EUR; 1,235 JPY).
+ * One too small for them keeps six significant figures instead of reading 0.
+ */
+function formatFxAmount(amount: number, currency: string): string {
+  const digits = currencyMinorDigits(currency);
+  const rounded = Number(amount.toFixed(digits));
+  if (rounded === 0 && amount !== 0) return `${formatFxRate(amount)} ${currency}`;
+  const text = amount.toLocaleString("en-US", { minimumFractionDigits: digits, maximumFractionDigits: digits });
+  return `${text} ${currency}`;
+}
+
+/** `1,234.50 EUR = 1,383.47 USD`: the amount and what it converts to at the rate. */
+export function describeFxConversion(request: FxRequest, amount: number, rate: number): string {
+  return `${formatFxAmount(amount, request.currency)} = ${formatFxAmount(amount * rate, request.baseCurrency)}`;
+}
+
 /**
  * The rate of `currency` in `baseCurrency` from each one's USD value (USD per
  * unit), the way every cross is built. NaN when a leg is missing or unusable.

package/src/cli/glossary.ts

@@ -2,7 +2,7 @@ import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText
 
 /**
  * Plain-words meanings of the rates, auction, energy, perpetual-futures, portfolio,
- * fund, short interest, quote-board, futures and economic-calendar terms the functions
+ * fund, short interest, quote-board, futures (basis, contango, roll yield) 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
@@ -301,10 +301,11 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
       + "The funding rate keeps its price close to the asset it tracks.",
   },
   {
-    term: "Funding rate", aliases: ["funding", "funding payment", "funding fee", "funding 8h"], functions: ["PERP"],
-    shown: ["Funding %/int", "Funding 8h", "Paid %/int"],
+    term: "Funding rate", aliases: ["funding", "funding payment", "funding fee", "funding 8h", "funding apr", "apr"], functions: ["PERP"],
+    shown: ["Funding %/int", "Funding 8h", "Paid %/int", "APR %"],
     definition: "A regular payment between the two sides of a perpetual contract, set to pull its price toward the asset's. "
-      + "Positive means longs pay shorts, negative means shorts pay longs.",
+      + "Positive means longs pay shorts, negative means shorts pay longs, so a basis trade (long spot, short the perpetual) collects it when positive. "
+      + "APR % is the current 8h rate × 3 × 365: a simple annualisation of the rate now, not funding actually paid.",
   },
   {
     term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP"],
@@ -473,6 +474,35 @@ 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.",
   },
+  // 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"],
+    functions: ["CTM", "FUT", "PERP"], shown: ["Vs Spot", "VS SPOT"],
+    definition: "The gap between a futures price and the spot price of what it tracks, in percent: positive when the future costs more, negative when it costs less. "
+      + "It closes by expiry. A basis trade buys spot and sells the future to earn it. A perpetual has no expiry, so its funding rate plays that part.",
+  },
+  {
+    term: "Annualised basis", aliases: ["annualized basis", "ann basis", "ann. basis", "basis annualised"], functions: ["CTM", "PERP"], shown: ["Ann Basis", "ANN BASIS"],
+    definition: "The basis restated as a yearly rate, so contracts of different length compare with each other and with a perpetual's funding APR: "
+      + "(Last / spot - 1) × 365 / days to expiry, simple rather than compounded, on the latest trade against the spot quote. "
+      + "Inside 30 days a few basis points of spot noise move it by whole points: 10 bp is about ±2 points at 18 days to expiry.",
+  },
+  {
+    term: "Contango", aliases: ["contango curve", "upward curve"], functions: ["CTM", "FUT"], shown: ["contango", "Contango"],
+    definition: "A futures curve that slopes up: each contract costs more than the one before it, and the future trades above spot. "
+      + "A long rolling into the next contract pays that difference, a short earns it, and the basis closes as expiry nears.",
+  },
+  {
+    term: "Backwardation", aliases: ["backwardation curve", "downward curve", "inverted futures curve"], functions: ["CTM", "FUT"], shown: ["backwardation", "Backwardation"],
+    definition: "A futures curve that slopes down: later contracts cost less than nearer ones, and the future trades below spot, often when the asset is scarce now. "
+      + "A long rolling into the next contract earns that difference, a short pays it.",
+  },
+  {
+    term: "Roll yield", aliases: ["roll", "roll return", "annualised roll yield", "annualized roll yield", "ann roll yield", "ann. roll yield"], functions: ["CTM", "FUT"],
+    shown: ["Ann. roll yield", "Annualized Roll Yield"],
+    definition: "What a long future earns or loses as it is rolled into the next contract. CTM's annualised roll yield is the front price over the next contract's "
+      + "less 1, scaled to a year: (front / next - 1) × 365 / days between the two. It is positive in backwardation and negative in contango.",
+  },
   // The economic calendar (ECO).
   {
     term: "Actual", aliases: ["actual release", "actual value"], functions: ["ECO"], shown: ["ACTUAL", "Actual"],

package/src/cli/history-rows.ts

@@ -16,6 +16,8 @@ import { getPricePointTimestamp } from "../utils/price-history";
 import { pricePointIntegrityFlags, pricePointValues } from "../utils/price-history-integrity";
 import { formatUtcTime } from "../utils/utc-time";
 import { historyCoverageNotice } from "../sources/history-coverage";
+import { barPeriodToDate, type BarPeriodToDate } from "../market-data/market/bar-period";
+import { barSizeFromGap, medianBarGap } from "../time-series/bar-spacing";
 
 const PRICE_KEYS = ["open", "high", "low", "close"] as const;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -33,7 +35,7 @@ const BREAK_JUMP_RATIO = 100;
 const BREAK_FLAGS: ReadonlySet<string> = new Set(["gap", "jump"]);
 const FIRST_MONDAY_MS = Date.UTC(1970, 0, 5);
 
-const BAR_INTERVAL_LABELS: Record<ManualChartResolution, string> = {
+export const BAR_INTERVAL_LABELS: Record<ManualChartResolution, string> = {
   "1m": "1-minute",
   "5m": "5-minute",
   "15m": "15-minute",
@@ -107,32 +109,25 @@ function isUtcMidnight(time: number): boolean {
   return new Date(time).toISOString().endsWith("T00:00:00.000Z");
 }
 
-function medianGap(times: readonly number[]): number | null {
-  const finite = times.filter(Number.isFinite).sort((left, right) => left - right);
-  const gaps = finite.slice(1).map((time, index) => time - finite[index]!).filter((gap) => gap > 0).sort((left, right) => left - right);
-  return gaps.length > 0 ? gaps[Math.floor((gaps.length - 1) / 2)]! : null;
-}
-
 /** Without a declared cadence, bar spacing decides: daily bars may be stamped at the session open. */
 function looksIntraday(times: readonly number[]): boolean {
   const finite = times.filter(Number.isFinite);
   if (finite.length < 2) return finite.some((time) => !isUtcMidnight(time));
-  const gap = medianGap(finite);
+  const gap = medianBarGap(finite);
   return gap != null && gap < INTRADAY_MAX_GAP_MS;
 }
 
 /** The bar size served: as the source declared it, otherwise read from the typical spacing of the bars. */
 function historyInterval(times: readonly number[], resolution: ManualChartResolution | null): ManualChartResolution | null {
   if (resolution) return resolution;
-  const gap = medianGap(times);
+  const gap = medianBarGap(times);
   if (gap == null) return null;
   if (gap < INTRADAY_MAX_GAP_MS) {
     return INTRADAY_RESOLUTIONS.reduce((best, candidate) => (
       Math.abs(CHART_RESOLUTION_STEP_MS[candidate] - gap) < Math.abs(CHART_RESOLUTION_STEP_MS[best] - gap) ? candidate : best
     ));
   }
-  const days = gap / DAY_MS;
-  return days >= 25 ? "1mo" : days >= 6 ? "1wk" : "1d";
+  return barSizeFromGap(gap);
 }
 
 /**
@@ -233,6 +228,25 @@ export function historyRows(
   });
 }
 
+/**
+ * The newest weekly or monthly bar while its period has not ended at `now`
+ * (barPeriodToDate): marked `partial`, as a bar its source marks is, with
+ * how far into its period it runs, which the status line names (`month to
+ * date, through Thu 15 Oct 2026`). Daily and intraday bars are left as the
+ * source marks them. Null when the newest bar is complete.
+ */
+export function formingPeriodBar(
+  rows: readonly HistoryRow[],
+  venue: string | undefined,
+  now = Date.now(),
+): { rows: HistoryRow[]; periodToDate: BarPeriodToDate } | null {
+  const last = rows.at(-1);
+  const period = last?.interval === "1mo" ? "month" : last?.interval === "1wk" ? "week" : null;
+  const forming = last && period ? barPeriodToDate(last.date, period, venue, now) : null;
+  if (!forming) return null;
+  return { rows: [...rows.slice(0, -1), { ...last!, partial: true }], periodToDate: forming };
+}
+
 /**
  * The volume of a coin's history: traded value in the quote currency the
  * prices are in. Null for anything else, whose volume stays unlabelled.

package/src/cli/index.ts

@@ -37,8 +37,8 @@ import { createSystemCliCommands } from "./commands/system";
 import { brokerCliCommand, ibkrCliCommand } from "./commands/broker";
 import { listPlugins, updatePlugins } from "./commands/plugins";
 import { installListedPlugin, removePlugin } from "../plugins/installer";
-import { catalogCommandHits, functionCodeCommand, runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
-import { catalogPointer, type CatalogCommandHit } from "./unknown-command";
+import { catalogCommandHits, functionCodeCommand, nearFunctionCodeCommand, runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
+import { catalogPointer, tickerPointer, type CatalogCommandHit } from "./unknown-command";
 import { catalogFredSeriesIds } from "./series-search";
 
 const { width: SHOT_WIDTH, height: SHOT_HEIGHT } = SHOT_SIZE_LIMITS;
@@ -251,6 +251,12 @@ function createCoreCliCommands(
       help: {
         group: CLI_COMMAND_GROUPS.plugins,
         usage: ["update [name]"],
+        sections: [{
+          title: "Updating Gloomberb itself",
+          lines: [
+            "The app updates itself from stable releases. config set updates.channel nightly adds the nightly build of main; see gloomberb help config.",
+          ],
+        }],
         examples: ["update", "update gloom-tv"],
       },
       execute: async (args) => {
@@ -317,6 +323,8 @@ function nearCommand(token: string, commands: CliCommandDef[]): string | null {
 interface UnknownCommandPointers {
   /** The word is a function's code: the command that runs it. */
   fn: { code: string; command: string } | null;
+  /** The word is a slip from one function's code (RCDF for RDCF), read only when it is no code, no command is close to it and the catalog finds nothing for it. */
+  nearFn: { code: string; label: string; command: string } | null;
   /** Functions the catalog finds for the word, read only when it is no code and no command is close to it. */
   hits: CatalogCommandHit[];
   /** What the reader typed after the word, which a pointer runs the function with. */
@@ -331,24 +339,34 @@ async function unknownCommandPointers(
   commands: CliCommandDef[],
 ): Promise<UnknownCommandPointers> {
   const fn = await functionCodeCommand(ctx, token, args);
-  const hits = fn || nearCommand(token, commands) ? [] : await catalogCommandHits(ctx, token);
-  return { fn, hits, args };
+  const command = fn || nearCommand(token, commands);
+  const hits = command ? [] : await catalogCommandHits(ctx, token);
+  // What the catalog finds for a word (`comps`) outranks the code it happens to be a slip from.
+  const nearFn = command || hits.length > 0 ? null : await nearFunctionCodeCommand(ctx, token, args);
+  return { fn, nearFn, hits, args };
 }
 
 /**
  * A function's code is pointed at `fn`; a typo of a command at the command;
- * a word the catalog knows (`comps`, `peers`) at the functions it finds.
+ * a typo of a function's code (`RCDF`) at that function; a word the catalog
+ * knows (`comps`, `peers`) at the functions it finds. A word written as a
+ * ticker (`PLTR`) is also pointed at `quote` and `search`.
  */
 function failUnknownCommand(token: string, commands: CliCommandDef[], pointers: UnknownCommandPointers): never {
   if (pointers.fn) fail(`${pointers.fn.code} is a function: ${pointers.fn.command}`);
+  const ticker = tickerPointer(token);
   const suggestion = nearCommand(token, commands);
+  if (!suggestion && pointers.nearFn) {
+    fail(
+      `Unknown command "${token}". Did you mean the function ${pointers.nearFn.code} (${pointers.nearFn.label})?`,
+      [`Run: ${pointers.nearFn.command}`, ticker].filter(Boolean).join("\n"),
+    );
+  }
   const catalog = suggestion ? null : catalogPointer(token, pointers.hits, pointers.args);
-  fail(
-    `Unknown command "${token}".`,
-    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.",
-  );
+  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.";
+  fail(`Unknown command "${token}".`, ticker ? `${ticker}\n${help}` : help);
 }
 
 const CLI_DESCRIPTION = "Market research and portfolio tracker for the terminal";
@@ -443,7 +461,7 @@ export async function failUnknownCliCommand(args: string[], options: DispatchCli
   // functions, with the arguments the reader gave.
   const pointers = token && parsed
     ? await unknownCommandPointers(createCliCommandContext("core", registry, parsed.options, parsed.args.slice(1)), token, parsed.args.slice(1), commands)
-    : { fn: null, hits: [], args: [] };
+    : { fn: null, nearFn: null, hits: [], args: [] };
   return failUnknownCommand(token, commands, pointers);
 }