gloomberb 0.16.3 → 0.16.4

package/src/cli/help.ts

@@ -34,15 +34,25 @@ const INDENT = 2;
 const MAX_HELP_WIDTH = 100;
 const PIPED_HELP_WIDTH = 80;
 
+/** Commands that run as written, for someone who has just installed it. */
+const START_HERE: Array<[string, string]> = [
+  ["gloomberb search apple", "Find a ticker from a company name"],
+  ["gloomberb quote AAPL", "Show the latest price"],
+  ["gloomberb ticker AAPL", "Open the full research report"],
+  ["gloomberb catalog earnings", "Find a function, then run it with fn"],
+];
+
 const GLOBAL_OPTIONS: Array<[string, string]> = [
   ["--json", "Print the full result as JSON"],
   ["--csv", "Print rows as CSV under the columns the text shows; fn reports and fundamentals put each table under # section: and end with # source lines"],
   ["--ndjson", "Print one JSON object per table row"],
-  ["--limit <n>", "Show at most n rows"],
+  ["--limit <n>", "Show at most n rows, the first n as printed"],
+  ["--tail <n>", "Show the newest n rows of a dated series (history, fred, econ) in their printed order, or the last n of another list"],
   ["--refresh", "Fetch fresh data instead of reading the cache"],
   ["--dry-run", "Preview config, cache, notes, alerts, plugin on/off, and remote changes without saving"],
   ["-q, --quiet", "Print no results or errors in text mode, for commands that print results"],
   ["--color, --no-color", "Force or turn off colors (NO_COLOR=1 also turns them off)"],
+  ["--width <n>", "Fit tables to n columns (default: the terminal width; piped output is not fitted). shot takes its own --width in pixels"],
 ];
 
 export interface CliHelpEntry {
@@ -98,6 +108,9 @@ export function renderCliHelp(entries: CliHelpEntry[], version: string, descript
     `${cliStyles.bold("gloomberb")} ${cliStyles.muted(version)}`,
     ...wrapText(description, width),
     "",
+    renderSection("Start here"),
+    ...renderDefinitions(START_HERE, { width, termStyle: cliStyles.command }),
+    "",
     renderSection("Usage"),
     ...renderDefinitions([
       ["gloomberb", "Open the terminal UI"],

package/src/cli/index-roots.ts

@@ -0,0 +1,51 @@
+/**
+ * Well-known index roots that people type bare. As a bare symbol each one is
+ * another instrument (MOVE is Corvex, MID a fund) or nothing at all (VIX); the
+ * index itself is quoted as ^ROOT. Every entry is offered as a command to run,
+ * so only roots whose ^ symbol returns a quote belong here.
+ */
+const INDEX_ROOTS = new Map([
+  ["VIX", "Cboe Volatility Index"],
+  ["VVIX", "Cboe VIX of VIX Index"],
+  ["VIX9D", "Cboe S&P 500 9-Day Volatility Index"],
+  ["VIX3M", "Cboe S&P 500 3-Month Volatility Index"],
+  ["VXN", "Cboe Nasdaq-100 Volatility Index"],
+  ["OVX", "Cboe Crude Oil ETF Volatility Index"],
+  ["GVZ", "Cboe Gold ETF Volatility Index"],
+  ["SKEW", "Cboe SKEW Index"],
+  ["TNX", "Cboe 10-Year Treasury Yield Index"],
+  ["SPX", "S&P 500 Index"],
+  ["OEX", "S&P 100 Index"],
+  ["MID", "S&P MidCap 400 Index"],
+  ["DJI", "Dow Jones Industrial Average"],
+  ["NDX", "Nasdaq-100 Index"],
+  ["SOX", "PHLX Semiconductor Index"],
+  ["RUT", "Russell 2000 Index"],
+  ["RUI", "Russell 1000 Index"],
+  ["RUA", "Russell 3000 Index"],
+  ["MOVE", "ICE BofA MOVE Index"],
+  ["NYA", "NYSE Composite Index"],
+]);
+
+export interface IndexRoot {
+  /** The index's own symbol: ^VIX. */
+  symbol: string;
+  name: string;
+}
+
+/** The index a bare root names (VIX is ^VIX); null for any other symbol, ^VIX included. */
+export function indexRootFor(symbol: string): IndexRoot | null {
+  const root = symbol.trim().toUpperCase();
+  const name = INDEX_ROOTS.get(root);
+  return name ? { symbol: `^${root}`, name } : null;
+}
+
+/** "^VIX  Cboe Volatility Index (try: gloomberb quote ^VIX)", under a bare root that found nothing. */
+export function indexRootTryLine(root: IndexRoot, command = "quote"): string {
+  return `${root.symbol}  ${root.name} (try: gloomberb ${command} ${root.symbol})`;
+}
+
+/** "also ^MOVE ICE BofA MOVE Index (gloomberb quote ^MOVE)", under a bare root that quoted another instrument. */
+export function indexRootAlsoLine(root: IndexRoot, command = "quote"): string {
+  return `also ${root.symbol} ${root.name} (gloomberb ${command} ${root.symbol})`;
+}

package/src/cli/index.ts

@@ -21,8 +21,8 @@ import {
 } from "./help";
 import { parsePaneFunctionArgs } from "./pane-functions/options";
 import { checkCliCommandOptions } from "./command-options";
-import { fail, inferCliErrorOptions, printCliError } from "./errors";
-import { setCliColorEnabledOverride } from "../utils/cli-output";
+import { asUsageError, fail, inferCliErrorOptions, printCliError } from "./errors";
+import { setCliColorEnabledOverride, setCliWidthOverride } from "../utils/cli-output";
 import { search, searchCandidatesForCli, buildSearchReport } from "./commands/search";
 import { ticker } from "./commands/ticker";
 import { requireOneArg, takeOption } from "./commands/command-utils";
@@ -176,9 +176,10 @@ function createCoreCliCommands(
           { flags: "--output <path>", description: "PNG to write; defaults to gloomberb-<function>-<argument>.png in this folder" },
           { flags: "--width <px>", description: "Image width, 720 to 2400 (default 1280)" },
           { flags: "--height <px>", description: "Image height, 360 to 1800 (default 720)" },
-          { flags: "--theme <id>", description: "Render with another theme, such as amber or green" },
+          { flags: "--theme <id>", description: "Render with another theme, such as amber or colorblind; gloomberb config themes lists them" },
           { flags: "--scale <n>", description: "Text scale from 0.5 to 4 (default 1)" },
           { flags: "--watermark <label>", description: "Label drawn in the pane title bar" },
+          { flags: "--no-status", description: "Leave out the dated status line (as-of, delay, market hours) drawn in the pane footer" },
           { flags: "--<option> <value>", description: "A function setting; gloomberb catalog <function> lists them" },
           EXCHANGE_OPTION,
         ],
@@ -187,6 +188,7 @@ function createCoreCliCommands(
           "shot HP BHP:ASX",
           "shot DDIS MSFT --tab history",
           "shot HP NVDA --width 1600 --theme green",
+          "shot QQ AAPL,MSFT --no-status",
         ],
       },
       execute: async (args, ctx) => {
@@ -336,11 +338,12 @@ export async function dispatchCli(args: string[], options: DispatchCliOptions =
   try {
     parsed = parseCliGlobalArgs(args);
   } catch (error) {
-    printCliError(error, inferCliErrorOptions(args));
+    printCliError(asUsageError(error), inferCliErrorOptions(args));
     process.exitCode = 1;
     return { kind: "handled" };
   }
   setCliColorEnabledOverride(parsed.options.color);
+  setCliWidthOverride(parsed.options.width ?? null);
   const command = parsed.args[0] ?? (parsed.help ? "help" : undefined);
   if (!command) {
     return { kind: "unhandled" };
@@ -361,11 +364,11 @@ export async function dispatchCli(args: string[], options: DispatchCliOptions =
     if (!helpOnly && resolved.builtin) checkCliCommandOptions(resolved.command, commandArgs, parsed.literalStart - 1);
     const result = await target.command.execute(
       commandArgs,
-      createCliCommandContext(target.ownerId, registry, parsed.options),
+      createCliCommandContext(target.ownerId, registry, parsed.options, commandArgs),
     );
     return normalizeCliDispatchResult(result);
   } catch (error) {
-    printCliError(error, parsed.options, { command: resolved.command.name });
+    printCliError(error, parsed.options, { command: resolved.command.name, args: commandArgs });
     process.exitCode = 1;
     return { kind: "handled" };
   }

package/src/cli/listing-arg.ts

@@ -8,10 +8,13 @@ import {
   canonicalExchange,
   exchangeLabel,
   isKnownExchangeCode,
+  isUsListingExchange,
   parsePublicTickerKey,
   publicTickerKey,
+  resolveExchangeTimeZone,
 } from "../utils/exchanges";
 import { withMarketData } from "./scoped-context";
+import { isNoProviderMessage } from "../sources/provider-errors";
 
 /** The `--exchange` option of every command that takes a ticker. */
 export const EXCHANGE_OPTION = {
@@ -156,32 +159,237 @@ export async function failIfNotTraded(
   if (message) ctx.fail(message);
 }
 
+/** What a command asked a listing for, to name it when the listing has none: `history` asks for "history". */
+export interface ListingDataRequest {
+  /** The command a retry runs, with any options to repeat: `history`, `history --range 5Y`. */
+  command: string;
+  /** What the listing has none of: "history", "a quote". */
+  noun: string;
+}
+
+/**
+ * The router's answer when no source serves a symbol: "No history provider available for 2222",
+ * or "Not a ticker: 2222." when the service found no listing for it.
+ */
+export function isNoProviderError(error: unknown): boolean {
+  return isNoProviderMessage(error instanceof Error ? error.message : String(error ?? ""));
+}
+
+const MAX_OTHER_LISTINGS = 5;
+
+type BareListing = Pick<CliListing, "symbol" | "exchange"> & Partial<Pick<CliListing, "saved">>;
+
+/** Where a bare symbol went and where else it trades, in the order they are tried and named. */
+interface BareListingVenues {
+  /** Canonical code of the venue the symbol went to. */
+  exchange: string;
+  /** That venue as search lists it; null for a saved venue search no longer lists. */
+  resolved: ListingVenue | null;
+  /** The symbol's other venues, in search order. */
+  others: ListingVenue[];
+}
+
+/** A bare symbol goes to its saved listing, else to the one search lists first. Null when it named its exchange. */
+async function bareListingVenues(listing: BareListing, deps: ListingDeps): Promise<BareListingVenues | null> {
+  if (listing.exchange) return null;
+  const venues = await listingVenues(listing.symbol, deps).catch(() => []);
+  const savedExchange = canonicalExchange(listing.saved?.metadata.exchange);
+  const resolved = venues.find((venue) => venue.exchange === savedExchange) ?? (savedExchange ? null : venues[0] ?? null);
+  const exchange = resolved?.exchange ?? savedExchange;
+  if (!exchange) return null;
+  return { exchange, resolved, others: venues.filter((venue) => venue !== resolved && venue.exchange !== savedExchange) };
+}
+
+interface OtherListingsMessage {
+  message: string;
+  details: string;
+  /** SAN:EPA, for each other listing. */
+  others: string[];
+}
+
+function describeOtherListings(
+  listing: BareListing,
+  { exchange, resolved, others }: BareListingVenues,
+  request: ListingDataRequest,
+): OtherListingsMessage | null {
+  if (others.length === 0) return null;
+  const name = resolved?.name || listing.saved?.metadata.name?.trim() || "";
+  const [command, ...options] = request.command.split(" ");
+  const retry = (key: string) => ["gloomberb", command, key, ...options].join(" ");
+  const lines = others.slice(0, MAX_OTHER_LISTINGS).map((venue) => {
+    const key = `${listing.symbol}:${venue.exchange}`;
+    return `${key}${venue.name ? ` ${venue.name}` : ""} (try: ${retry(key)})`;
+  });
+  if (others.length > MAX_OTHER_LISTINGS) lines.push(`and ${others.length - MAX_OTHER_LISTINGS} more: gloomberb search ${listing.symbol}`);
+  return {
+    message: `${listing.symbol} resolved to ${name ? `${name} (${exchange})` : exchange}, which has no ${request.noun}.`,
+    details: lines.length === 1 ? `Other listings: ${lines[0]}` : ["Other listings:", ...lines.map((line) => `  ${line}`)].join("\n"),
+    others: others.map((venue) => `${listing.symbol}:${venue.exchange}`),
+  };
+}
+
+/**
+ * For a bare symbol whose request found no source: the listing it went to and
+ * the symbol's other listings, each with the command that asks for it, such
+ * as "2222 resolved to Kotobuki Spirits Co., Ltd. (JPX), which has no
+ * history." and "2222:TADAWUL Saudi Arabian Oil Co. (try: gloomberb history
+ * 2222:TADAWUL)". Null when the symbol named its exchange or has no other
+ * listing. It searches, so ask only after a request failed.
+ */
+async function otherListingsMessage(
+  listing: BareListing,
+  deps: ListingDeps,
+  request: ListingDataRequest,
+): Promise<OtherListingsMessage | null> {
+  const venues = await bareListingVenues(listing, deps);
+  return venues && describeOtherListings(listing, venues, request);
+}
+
+/** The listing on one venue, as `SYM:EXCH` names it. */
+function namedListing(listing: CliListing, exchange: string): CliListing {
+  const key = `${listing.symbol}:${exchange}`;
+  const saved = canonicalExchange(listing.saved?.metadata.exchange) === exchange ? listing.saved : null;
+  return { symbol: listing.symbol, exchange, key, saved, request: { symbol: key, exchange } };
+}
+
+async function quoteListings(
+  dataProvider: DataProvider,
+  listings: readonly CliListing[],
+  refresh: boolean,
+): Promise<Array<Quote | null>> {
+  if (listings.length === 0) return [];
+  const targets = listings.map((listing) => listing.request);
+  if (dataProvider.getQuotesBatch) {
+    const results = await dataProvider.getQuotesBatch(targets, { forceRefresh: refresh }).catch(() => []);
+    return targets.map((target, index) => (results.find((result) => result.target === target) ?? results[index])?.quote ?? null);
+  }
+  return Promise.all(targets.map((target) => dataProvider.getQuote(target.symbol, target.exchange, {
+    cacheMode: refresh ? "refresh" : "default",
+  }).catch(() => null)));
+}
+
+export type BareListingQuote =
+  | {
+    kind: "quoted";
+    /** The listing that has a quote: SXR8:XETRA. */
+    listing: CliListing;
+    quote: Quote;
+    /** "SXR8 -> XETRA (other listings: BUD, MUNICH)". */
+    note: string;
+  }
+  | ({ kind: "missing" } & OtherListingsMessage);
+
+/**
+ * The quote for a bare symbol no source quoted. The data service reads a
+ * symbol with no US listing on its home listing abroad (`bareListingNote`),
+ * so this is left for one it reads on none, as a code several companies list
+ * (2222 is Kotobuki Spirits in Tokyo and Saudi Aramco in Riyadh), and for a
+ * home listing with no quote. Search knows where the symbol trades: each
+ * listing is asked again by its own key (2222:JPX), as a named one is. The
+ * listing the symbol resolved to goes first, then the others together, and
+ * the first in search order with a quote is the answer. When none has one,
+ * the `otherListingsMessage` failure. Null when the symbol named its exchange
+ * (a named venue never switches) or search knows no listing of it. It
+ * searches, so ask only after a request failed.
+ */
+export async function quoteBareListing(
+  listing: CliListing,
+  deps: ListingDeps,
+  request: ListingDataRequest,
+  { refresh = false }: { refresh?: boolean } = {},
+): Promise<BareListingQuote | null> {
+  const venues = await bareListingVenues(listing, deps);
+  if (!venues) return null;
+  const first = [namedListing(listing, venues.exchange)];
+  const rest = venues.others.map((venue) => namedListing(listing, venue.exchange));
+  let tried = first;
+  let quotes = await quoteListings(deps.dataProvider, first, refresh);
+  if (!quotes[0] && rest.length > 0) {
+    tried = [...first, ...rest];
+    quotes = [...quotes, ...await quoteListings(deps.dataProvider, rest, refresh)];
+  }
+  const found = quotes.findIndex(Boolean);
+  if (found < 0) {
+    const other = describeOtherListings(listing, venues, request);
+    return other && { kind: "missing", ...other };
+  }
+  const answer = tried[found]!;
+  const without = tried.slice(0, found).map((entry) => entry.exchange);
+  // Listings not asked, or asked and quoted, are still there to name.
+  const others = [...first, ...rest]
+    .filter((entry, index) => entry !== answer && (index >= tried.length || quotes[index]))
+    .map((entry) => entry.exchange);
+  const more = others.length - MAX_OTHER_LISTINGS;
+  const aside = [
+    without.length > 0 ? `no quote on ${without.join(", ")}` : "",
+    others.length > 0
+      ? `other listings: ${others.slice(0, MAX_OTHER_LISTINGS).join(", ")}${more > 0 ? ` and ${more} more: gloomberb search ${listing.symbol}` : ""}`
+      : "",
+  ].filter(Boolean).join("; ");
+  return {
+    kind: "quoted",
+    listing: answer,
+    quote: quotes[found]!,
+    note: `${listing.symbol} -> ${answer.exchange}${aside ? ` (${aside})` : ""}`,
+  };
+}
+
+// The zones of the US exchanges; a venue in another is abroad.
+const US_TIME_ZONES = new Set(["America/New_York", "America/Chicago"]);
+
+/**
+ * "SXR8 -> XETRA" for a bare symbol the data service read on its home listing
+ * abroad, as it reads a symbol with no US listing whose listings belong to one
+ * company or fund: a row that shows the symbol as typed says which listing it
+ * is. Null for a named or saved venue, and for a venue the app does not place
+ * outside the US (a US exchange, OTC, a futures exchange).
+ */
+export function bareListingNote(
+  listing: Pick<CliListing, "symbol" | "request">,
+  quote: Pick<Quote, "listingExchangeName" | "exchangeName"> | null | undefined,
+): string | null {
+  if (listing.request.exchange || !quote || !/^[A-Z0-9]{1,10}$/.test(listing.symbol)) return null;
+  const venue = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+  const zone = resolveExchangeTimeZone(venue);
+  return zone && !US_TIME_ZONES.has(zone) && !isUsListingExchange(venue) ? `${listing.symbol} -> ${venue}` : null;
+}
+
 /**
  * A data request for the listings a command named. When it throws, or `isMiss`
  * calls what it returned empty, and a listing's exchange is one its symbol does
  * not trade on, the command ends in that message instead of the request's own
- * "unavailable". A request that succeeds costs no extra lookup.
+ * "unavailable". With `request`, a bare symbol no source serves ends naming
+ * its other listings (`otherListingsMessage`). A request that succeeds costs no
+ * extra lookup.
  */
 export async function loadForListing<T>(
-  listings: Pick<ListingArg, "symbol" | "exchange"> | readonly Pick<ListingArg, "symbol" | "exchange">[],
+  listings: ListingForLoad | readonly ListingForLoad[],
   deps: ListingDeps,
   ctx: Pick<CliCommandContext, "fail">,
   load: () => Promise<T>,
   isMiss?: (value: T) => boolean,
+  request?: ListingDataRequest,
 ): Promise<T> {
-  const named = ("symbol" in listings ? [listings] : listings).filter((listing) => listing.exchange);
+  const all = "symbol" in listings ? [listings] : listings;
+  const named = all.filter((listing) => listing.exchange);
   const checkVenues = () => Promise.all(named.map((listing) => failIfNotTraded(listing, deps, ctx)));
   let value: T;
   try {
     value = await load();
   } catch (error) {
     await checkVenues();
+    if (request && all.length === 1 && isNoProviderError(error)) {
+      const other = await otherListingsMessage(all[0]!, deps, request);
+      if (other) ctx.fail(other.message, other.details);
+    }
     throw error;
   }
   if (isMiss?.(value)) await checkVenues();
   return value;
 }
 
+type ListingForLoad = Pick<ListingArg, "symbol" | "exchange"> & Partial<Pick<CliListing, "saved">>;
+
 /** The saved ticker for a listing: under its own key, or a saved symbol whose venue it is. */
 export async function loadSavedListing(store: ListingStore, listing: ListingArg): Promise<TickerRecord | null> {
   if (!listing.exchange) return store.loadTicker(listing.symbol);

package/src/cli/not-a-ticker.ts

@@ -0,0 +1,37 @@
+import { notATickerSymbol } from "../sources/provider-errors";
+
+// "Not a ticker: APPLE." as the router words it; the symbol ends at the sentence's own period.
+const NOT_A_TICKER_SENTENCE = /Not a ticker: ((?:(?!\.\s)[^\n`\x1b])+?)\.(?=\s|\x1b|$)(?! Try `gloomberb search)/g;
+
+/** The symbol as the user typed it on the command line (`Apple`), not as the router saw it (`APPLE`). */
+function typedSymbol(symbol: string, args: readonly string[]): string {
+  const wanted = symbol.toUpperCase();
+  for (const arg of args) {
+    for (const part of arg.split(",")) {
+      const typed = part.trim().replace(/^\$/, "");
+      if (typed.toUpperCase() === wanted) return typed;
+    }
+  }
+  return symbol;
+}
+
+/** "Try `gloomberb search Apple`." naming what the user typed; a venue (`Apple:NYSE`) is not part of a search. */
+function searchHint(typed: string): string {
+  const query = typed.split(":")[0]!.trim() || typed;
+  return `Try \`gloomberb search ${/\s/.test(query) ? JSON.stringify(query) : query}\`.`;
+}
+
+/**
+ * Adds the search hint after each "Not a ticker: APPLE." in text meant for a person. The router
+ * only knows the symbol upper-cased, so the hint reads the user's own spelling from `args`.
+ */
+export function withSearchHints(text: string, args: readonly string[]): string {
+  return text.includes("Not a ticker: ")
+    ? text.replace(NOT_A_TICKER_SENTENCE, (sentence, symbol: string) => `${sentence} ${searchHint(typedSymbol(symbol, args))}`)
+    : text;
+}
+
+/** Whether an error message says the symbol is not a ticker. */
+export function isNotATickerMessage(message: string | null | undefined): boolean {
+  return message != null && notATickerSymbol(message) !== null;
+}

package/src/cli/options.ts

@@ -5,6 +5,10 @@ export interface CliGlobalOptions {
   quiet: boolean;
   color: boolean | null;
   limit?: number;
+  /** `--tail <n>`: the newest n rows of a dated series, in their printed order. Never set with `limit`. */
+  tail?: number;
+  /** `--width <n>`: fit tables to n columns. Unset, a terminal's own width fits them and piped output is not fitted. */
+  width?: number;
   refresh: boolean;
   dryRun: boolean;
   yes: boolean;
@@ -32,20 +36,44 @@ export const DEFAULT_CLI_OPTIONS: CliGlobalOptions = {
   yes: false,
 };
 
-function parseLimit(value: string | undefined): number {
-  if (!value) throw new Error("Missing value for --limit.");
+function parseRowCount(flag: "--limit" | "--tail", value: string | undefined): number {
+  if (!value) throw new Error(`Missing value for ${flag}.`);
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new Error("--limit must be a positive integer.");
+    throw new Error(`${flag} must be a positive integer.`);
   }
   return parsed;
 }
 
+/** Commands whose own `--width` is a size in pixels, so it is not the table width. */
+const PIXEL_WIDTH_COMMANDS = new Set(["shot", "screenshot"]);
+const MIN_TABLE_WIDTH = 20;
+
+function parseColumnCount(value: string | undefined): number {
+  const parsed = Number(value);
+  if (!value || !Number.isInteger(parsed) || parsed < MIN_TABLE_WIDTH) {
+    throw new Error(`--width must be a whole number of columns, ${MIN_TABLE_WIDTH} or more, such as --width 80.`);
+  }
+  return parsed;
+}
+
+/** The first word that is not an option or the value of one: the command the arguments are for. */
+function commandWord(rawArgs: readonly string[]): string | undefined {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index]!;
+    if (arg === "--") return rawArgs[index + 1];
+    if (arg === "--limit" || arg === "--tail" || arg === "--width") index += 1;
+    else if (!arg.startsWith("-")) return arg;
+  }
+  return undefined;
+}
+
 export function parseCliGlobalArgs(rawArgs: string[]): ParsedCliArgs {
   const options: CliGlobalOptions = { ...DEFAULT_CLI_OPTIONS };
   const args: string[] = [];
   let help = false;
   let literalStart: number | null = null;
+  const ownsWidth = PIXEL_WIDTH_COMMANDS.has(commandWord(rawArgs)?.toLowerCase() ?? "");
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index]!;
@@ -94,17 +122,33 @@ export function parseCliGlobalArgs(rawArgs: string[]): ParsedCliArgs {
       options.yes = true;
       continue;
     }
-    if (arg === "--limit") {
+    if (!ownsWidth && arg === "--width") {
       index += 1;
-      options.limit = parseLimit(rawArgs[index]);
+      options.width = parseColumnCount(rawArgs[index]);
+      continue;
+    }
+    if (!ownsWidth && arg.startsWith("--width=")) {
+      options.width = parseColumnCount(arg.slice("--width=".length));
+      continue;
+    }
+    if (arg === "--limit" || arg === "--tail") {
+      index += 1;
+      options[arg === "--limit" ? "limit" : "tail"] = parseRowCount(arg, rawArgs[index]);
       continue;
     }
     if (arg.startsWith("--limit=")) {
-      options.limit = parseLimit(arg.slice("--limit=".length));
+      options.limit = parseRowCount("--limit", arg.slice("--limit=".length));
+      continue;
+    }
+    if (arg.startsWith("--tail=")) {
+      options.tail = parseRowCount("--tail", arg.slice("--tail=".length));
       continue;
     }
     args.push(arg);
   }
+  if (options.limit != null && options.tail != null) {
+    throw new Error("Use --limit or --tail, not both: --limit keeps the first rows, --tail the newest.");
+  }
 
   return { args, options, help, literalStart: literalStart ?? args.length };
 }

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

@@ -9,6 +9,7 @@ import type {
 export type PaneFunctionReadiness = "ready" | "partial" | "live-dom" | "unsupported";
 type PaneFunctionScreenshotReadiness = PaneFunctionReadiness;
 type PaneFunctionTickerCardinality = "none" | "one" | "one-or-more" | "two-or-more" | "one-or-two";
+/** A headless option, or a rendered view's, which may name its value, show an example and check what is typed. */
 export type PaneFunctionOptionDef = HeadlessPaneOptionDef;
 export type NormalizedPaneFunctionOptions = Record<string, string | number | boolean>;
 
@@ -64,7 +65,7 @@ function fallbackCapability(
     limitations: [dataPane
       ? RENDERED_VIEW_LIMITATION
       : "This pane is an interactive surface and does not expose a data report."],
-    options: [],
+    options: [...(pane.reportOptions ?? [])],
   };
 }
 
@@ -159,6 +160,7 @@ function normalizeOptionValue(option: PaneFunctionOptionDef, rawValue: string |
     throw new Error(`Invalid --${option.key} value "${rawValue}". Use true or false.`);
   }
   if (rawValue === true) throw new Error(`--${option.key} requires a value.`);
+  if (option.normalize) return option.normalize(rawValue);
   if (option.type === "enum") return normalizeEnumValue(option, rawValue);
   if (option.type === "integer") {
     const value = Number(rawValue);
@@ -180,7 +182,11 @@ export function normalizeCapabilityOptions(
   settings: { strict?: boolean } = {},
 ): NormalizedPaneFunctionOptions {
   if (!capability.botSafe) {
-    return Object.fromEntries(Object.entries(options).map(([key, value]) => [key, value]));
+    // A rendered view takes any pane setting; the options it declares are checked.
+    return Object.fromEntries(Object.entries(options).map(([key, value]) => {
+      const option = resolveOptionDef(capability, key);
+      return option ? [option.key, normalizeOptionValue(option, value)] : [key, value];
+    }));
   }
 
   const normalized: Record<string, string | number | boolean> = {};

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

@@ -259,6 +259,11 @@ function paneCatalogSearchScore(entry: PaneCatalogEntry, query: string): number
   ].filter((value): value is string => !!value).join(" ").toLowerCase();
 
   let score = searchable.includes(query.toLowerCase()) ? 12 : 0;
+  // A query that is one of the function's own keywords ("hedge" for OSA) beats one found inside a
+  // longer keyword ("hedge funds" for 13F).
+  const keywords = [entry.label, ...entry.keywords, ...entry.capability.aliases]
+    .filter((value): value is string => !!value).map((value) => value.toLowerCase().replace(/\s+/g, " "));
+  if (keywords.includes(terms.join(" "))) score += 4;
   let matchedTerms = 0;
   for (const term of terms) {
     const normalized = normalizeLookupToken(term);
@@ -320,7 +325,8 @@ function optionChoices(option: PaneFunctionOptionDef): string[] {
 
 function optionFlags(option: PaneFunctionOptionDef): string {
   const choices = optionChoices(option).join("|");
-  return `--${option.key} <${choices && choices.length <= MAX_INLINE_CHOICES ? choices : option.values?.length ? "value" : option.type}>`;
+  const value = choices && choices.length <= MAX_INLINE_CHOICES ? choices : option.values?.length ? "value" : option.placeholder ?? option.type;
+  return `--${option.key} <${value}>`;
 }
 
 function optionDescription(option: PaneFunctionOptionDef): string {
@@ -365,7 +371,12 @@ function renderCatalogEntry(entry: PaneCatalogEntry): string {
   }
 
   lines.push("", renderSection("Examples"));
-  if (capability.reportReadiness !== "unsupported") lines.push(...wrapCommandLine(`gloomberb fn ${invocation}`, width));
+  if (capability.reportReadiness !== "unsupported") {
+    lines.push(...wrapCommandLine(`gloomberb fn ${invocation}`, width));
+    for (const option of capability.options) {
+      if (option.example) lines.push(...wrapCommandLine(`gloomberb fn ${invocation} ${option.example}`, width));
+    }
+  }
   lines.push(...wrapCommandLine(`gloomberb shot ${invocation} --output ${entry.token.toLowerCase()}.png`, width));
   return lines.join("\n");
 }