gloomberb 0.16.1 → 0.16.3

package/src/plugins/builtin/portfolio-list/cli/render.ts

@@ -1,14 +1,10 @@
 import { createBaseConverter } from "../../../../cli/base-converter";
 import { withMarketData } from "../../../../cli/scoped-context";
-import {
-  countCollectionTickers,
-  formatSignedCurrency,
-} from "../../../../cli/helpers";
+import { countCollectionTickers } from "../../../../cli/helpers";
 import {
   cliStyles,
   colorBySign,
   renderSection,
-  renderStats,
   renderTable,
 } from "../../../../utils/cli-output";
 import { formatCompact, formatPercentRaw } from "../../../../utils/format";
@@ -24,6 +20,24 @@ import type { MarketContext } from "../../../../cli/types";
 import type { Portfolio, TickerPosition, TickerRecord } from "../../../../types/ticker";
 import { instrumentFromTicker } from "../../../../market-data/request-types";
 import { toMarketDataContext } from "../../../../market-data/selectors";
+import { cliFreshnessFooter } from "../../../../cli/result";
+import { quotesFreshness } from "../../../../cli/freshness";
+import type { BrokerAccount } from "../../../../types/trading";
+import {
+  BROKER_ACCOUNT_MISSING_NOTE,
+  CASH_SYMBOL,
+  buildPortfolioAllocation,
+  describeTargetSum,
+  formatAllocationDrift,
+  formatAllocationMoney,
+  formatAllocationWeight,
+  formatTradeUnits,
+  hasTargetWeights,
+  resolvePortfolioCash,
+  type AllocationHolding,
+  type PortfolioAllocation,
+} from "../allocation";
+import { findCachedPortfolioAccount } from "../cached-account";
 
 /** Money prices pad to the currency's minor unit ($337.90, not $337.9), as the ticker view does. */
 function priceFormatOptions(quote: Parameters<typeof quoteFormatOptions>[0] & { currency?: string }, assetCategory?: string) {
@@ -141,6 +155,8 @@ interface PortfolioPositionValue {
 
 export interface PortfolioValuation {
   positions: PortfolioPositionValue[];
+  /** One per ticker, for weights and targets. */
+  holdings: AllocationHolding[];
   totalPnl: number;
   unavailablePnl: Set<string>;
   unavailableCost: Set<string>;
@@ -175,6 +191,7 @@ export async function valuePortfolioPositions({
   const unavailableMarketValue = new Set<string>();
   const brokerPnlSymbols = new Set<string>();
   const values: PortfolioPositionValue[] = [];
+  const holdings: AllocationHolding[] = [];
   const known = (value: number | null | undefined): number | null => value != null && Number.isFinite(value) ? value : null;
 
   for (const ticker of tickers) {
@@ -184,6 +201,9 @@ export async function valuePortfolioPositions({
     const activeQuote = displayedQuote && Number.isFinite(displayedQuote.price) ? displayedQuote : null;
 
     if (positions.length === 0) {
+      const quoteCurrency = quote?.currency || ticker.metadata.currency || baseCurrency;
+      const unitPrice = activeQuote ? known(await toBase(activeQuote.price, quoteCurrency)) : null;
+      holdings.push({ symbol: ticker.metadata.ticker, held: false, marketValue: 0, units: 0, unitPrice });
       values.push({ ticker, quote, activeQuote, position: null, metrics: null, pnl: null,
         row: { symbol: ticker.metadata.ticker, exchange: ticker.metadata.exchange, shares: null, avgCost: null,
           positionCurrency: null, quotePrice: known(activeQuote?.price), quoteCurrency: quote?.currency ?? null,
@@ -191,6 +211,8 @@ export async function valuePortfolioPositions({
       continue;
     }
 
+    const holding: AllocationHolding = { symbol: ticker.metadata.ticker, held: true, marketValue: 0, units: 0, unitPrice: null };
+    holdings.push(holding);
     for (const position of positions) {
       const quoteCurrency = quote?.currency || ticker.metadata.currency || baseCurrency;
       const metrics = getPortfolioPositionMetrics({ ...ticker, metadata: { ...ticker.metadata, positions: [position] } }, id, quoteCurrency, undefined, quote);
@@ -212,24 +234,72 @@ export async function valuePortfolioPositions({
       if (pnl != null && Number.isFinite(pnl)) totalPnl += pnl;
       else unavailablePnl.add(ticker.metadata.ticker);
       const direction = metrics.totalShares < 0 ? -1 : 1;
+      const marketValue = currentValueBase == null ? null : known(direction * currentValueBase);
+      holding.marketValue = holding.marketValue == null || marketValue == null ? null : holding.marketValue + marketValue;
+      holding.units += metrics.totalShares;
+      holding.unitPrice ??= valuationQuote ? known(await toBase(valuationQuote.price, quoteCurrency)) : null;
       values.push({ ticker, quote, activeQuote, position, metrics, pnl,
         row: { symbol: ticker.metadata.ticker, exchange: ticker.metadata.exchange,
           shares: metrics.totalShares, avgCost: known(position.avgCost), positionCurrency,
           priceBasis: position.priceBasis ?? null, quantityUnit: metrics.priceBasis === "percent-of-par" ? "face" : null, quotePriceBasis: quote?.priceBasis ?? null,
           quotePrice: known(activeQuote?.price), quoteCurrency, quoteAsOf: quote?.lastUpdated ?? null,
-          costBasis: known(direction * costBasisBase), marketValue: currentValueBase == null ? null : known(direction * currentValueBase),
+          costBasis: known(direction * costBasisBase), marketValue,
           unrealizedPnl: known(pnl), baseCurrency: currency, dateAcquired: position.dateAcquired ?? null,
           pnlBasis: selectedPnl.basis, brokerUnrealizedPnl: known(position.unrealizedPnl), brokerPnlCurrency: positionCurrency, brokerPnlAsOf: null } });
     }
   }
 
-  return { positions: values, totalPnl, unavailablePnl, unavailableCost, unavailableMarketValue, brokerPnlSymbols };
+  return { positions: values, holdings, totalPnl, unavailablePnl, unavailableCost, unavailableMarketValue, brokerPnlSymbols };
+}
+
+/** A portfolio's cash line, as `portfolio show` and `fn PF` report it. */
+export interface PortfolioCashReport {
+  /** In the cash's own currency. */
+  amount: number;
+  currency: string;
+  /** Recorded with `portfolio cash set`, or reported by the broker account. */
+  source: "manual" | "broker";
+  /** In the portfolio's currency; null when the rate is unavailable. */
+  value: number | null;
+}
+
+/**
+ * Weights, targets and trades for a valued portfolio, with its cash: the
+ * broker account's when it reports one, else the amount entered by hand.
+ */
+export async function valuePortfolioAllocation({
+  valuation,
+  portfolio,
+  account,
+  toBase,
+}: {
+  valuation: Pick<PortfolioValuation, "holdings">;
+  portfolio: Portfolio;
+  account?: BrokerAccount | null;
+  toBase: (value: number, fromCurrency: string) => Promise<number>;
+}): Promise<{ allocation: PortfolioAllocation; cash: PortfolioCashReport | null }> {
+  const line = resolvePortfolioCash(portfolio, account);
+  const value = line && line.currency ? await toBase(line.amount, line.currency) : null;
+  const cash = line ? { amount: line.amount, currency: line.currency, source: line.source, value: value != null && Number.isFinite(value) ? value : null } : null;
+  const allocation = buildPortfolioAllocation({
+    holdings: valuation.holdings,
+    cashValue: cash ? cash.value ?? Number.NaN : null,
+    targets: portfolio.targetWeights,
+  });
+  return { allocation, cash };
 }
 
+/** Colors a signed figure only when its text shows a nonzero digit. */
+function signed(text: string, value: number | null | undefined): string {
+  return /[1-9]/.test(text) ? colorBySign(text, value) : text;
+}
+
+const NOT_AVAILABLE = "n/a";
+
 async function showCollectionWithMarketData(
   name: string,
   ctx: CliCommandContext,
-  { config, store, dataProvider }: MarketContext,
+  { config, store, dataProvider, persistence }: MarketContext,
 ) {
   const tickers = (await store.loadAllTickers()).sort((left, right) =>
     left.metadata.ticker.localeCompare(right.metadata.ticker)
@@ -254,14 +324,22 @@ async function showCollectionWithMarketData(
   // A portfolio reports in its own currency, as its pane totals; a watchlist in the base currency.
   const currency = resolvePortfolioTotalsCurrency(matchedPortfolio, config.baseCurrency);
   const toBase = createBaseConverter(dataProvider, currency);
+  const account = matchedPortfolio ? findCachedPortfolioAccount(config, matchedPortfolio, persistence?.resources) : null;
+  const hasCash = !!resolvePortfolioCash(matchedPortfolio, account) || hasTargetWeights(matchedPortfolio);
 
-  if (filtered.length === 0 && !structured) {
+  if (filtered.length === 0 && !structured && !hasCash) {
     console.log(cliStyles.bold(displayName));
     console.log(cliStyles.muted("No tickers in this collection."));
     return;
   }
 
   const quotes = await loadCollectionQuotes(filtered, collection, dataProvider);
+  // Worst of across the holdings' quotes, as the PORT and watchlist reports state it.
+  const broker = !!(matchedPortfolio?.brokerId || matchedPortfolio?.brokerInstanceId);
+  const freshness = quotesFreshness(quotes.values(), {
+    source: !isPortfolio ? "Local watchlist and Gloom Cloud"
+      : broker ? "Your broker account and Gloom Cloud" : "Local portfolio and Gloom Cloud",
+  });
 
   if (!structured) {
     console.log(cliStyles.bold(displayName + (isPortfolio ? ` (${currency})` : "")));
@@ -269,7 +347,8 @@ async function showCollectionWithMarketData(
     console.log("");
   }
 
-  if (isPortfolio) {
+  if (matchedPortfolio) {
+    const valuation = await valuePortfolioPositions({ tickers: filtered, quotes, portfolioId: id, currency, baseCurrency: config.baseCurrency, toBase });
     const {
       positions: valued,
       totalPnl,
@@ -277,56 +356,170 @@ async function showCollectionWithMarketData(
       unavailableCost,
       unavailableMarketValue,
       brokerPnlSymbols,
-    } = await valuePortfolioPositions({ tickers: filtered, quotes, portfolioId: id, currency, baseCurrency: config.baseCurrency, toBase });
-    const positionsExport = valued.map((entry) => entry.row);
-    const rows: string[][] = valued.map(({ ticker, quote, activeQuote, position, metrics, pnl }) => {
+    } = valuation;
+    const { allocation, cash } = await valuePortfolioAllocation({ valuation, portfolio: matchedPortfolio, account, toBase });
+    const allocationBySymbol = new Map(allocation.rows.map((row) => [row.symbol, row]));
+    const showTargets = allocation.targetSum != null;
+    // A ticker held in several lots carries its allocation on its first row.
+    const firstRows = new Set<string>();
+    const positionsExport = valued.map((entry): Record<string, unknown> & {
+      weight: number | null; targetWeight: number | null; drift: number | null; tradeShares: number | null; tradeValue: number | null;
+    } => {
+      const symbol = entry.ticker.metadata.ticker;
+      const first = !firstRows.has(symbol);
+      firstRows.add(symbol);
+      const figures = first ? allocationBySymbol.get(symbol) : undefined;
+      return {
+        ...entry.row,
+        weight: figures?.weight ?? null,
+        targetWeight: figures?.targetWeight ?? null,
+        drift: figures?.drift ?? null,
+        tradeShares: figures?.tradeUnits ?? null,
+        tradeValue: figures?.tradeValue ?? null,
+      };
+    });
+    const totalPnlValue = unavailablePnl.size > 0 ? null : totalPnl;
+    const cashExport = cash && allocation.cash ? {
+      ...cash,
+      weight: allocation.cash.weight,
+      targetWeight: allocation.cash.targetWeight,
+      drift: allocation.cash.drift,
+      tradeValue: allocation.cash.tradeValue,
+    } : allocation.cash ? {
+      amount: 0, currency, source: "manual" as const, value: 0,
+      weight: allocation.cash.weight, targetWeight: allocation.cash.targetWeight,
+      drift: allocation.cash.drift, tradeValue: allocation.cash.tradeValue,
+    } : null;
+
+    const accountingBasis = "Unrealized P&L on current positions; excludes realized trades, distributions and cash flows. This is not account investment return.";
+    const manualAccounting = !matchedPortfolio.brokerId && !matchedPortfolio.brokerInstanceId
+      ? "Manual holdings are snapshots. Reconcile shares and per-share cost after corporate actions using portfolio position set; cash distributions are not credited."
+      : null;
+    if (structured) {
+      // CSV and NDJSON read the cash and the total as rows; JSON keeps them in the metadata.
+      const extraRows: Record<string, unknown>[] = [
+        ...(cashExport ? [{ symbol: CASH_SYMBOL, marketValue: cashExport.value, baseCurrency: currency, weight: cashExport.weight,
+          targetWeight: cashExport.targetWeight, drift: cashExport.drift, tradeShares: null, tradeValue: cashExport.tradeValue }] : []),
+        { symbol: "TOTAL", marketValue: allocation.total, unrealizedPnl: totalPnlValue, baseCurrency: currency,
+          weight: allocation.total != null && allocation.total > 0 ? 100 : null, targetWeight: allocation.targetSum },
+      ];
+      ctx.printResult({ data: positionsExport, metadata: {
+        portfolioId: id, portfolioName: displayName, baseCurrency: currency, currency,
+        total: allocation.total, cash: cashExport, targetSum: allocation.targetSum,
+        unpricedCount: allocation.unpriced.length, unpricedSymbols: allocation.unpriced,
+        totalUnrealizedPnl: totalPnlValue,
+        complete: unavailablePnl.size === 0 && unavailableCost.size === 0 && unavailableMarketValue.size === 0,
+        unavailableSymbols: [...new Set([...unavailablePnl, ...unavailableCost, ...unavailableMarketValue])],
+        unavailableCostSymbols: [...unavailableCost], brokerPnlSymbols: [...brokerPnlSymbols],
+        accountingBasis, ...(manualAccounting ? { manualAccounting } : {}),
+      }, freshness }, { rows: (data) => [...(data as Record<string, unknown>[]), ...extraRows] });
+      return;
+    }
+
+    const money = (value: number | null | undefined, options?: { signed?: boolean }) => formatAllocationMoney(value, currency, options);
+    // Values and trades in whole units keep the table inside 80 columns; prices, costs and P&L keep the minor unit.
+    const wholeMoney = (value: number | null | undefined, options?: { signed?: boolean }) => formatAllocationMoney(value, currency, { ...options, whole: true });
+    const allocationCells = (
+      figures: { weight: number | null; targetWeight: number | null; drift: number | null; tradeValue: number | null; tradeUnits?: number | null } | undefined,
+      { unpriced, units, assetCategory }: { unpriced: boolean; units?: number; assetCategory?: string },
+    ): string[] => {
+      const missing = unpriced ? NOT_AVAILABLE : "—";
+      const weight = figures?.weight != null ? formatAllocationWeight(figures.weight) : missing;
+      if (!showTargets) return [weight];
+      const target = figures?.targetWeight != null ? formatAllocationWeight(figures.targetWeight) : "—";
+      const hasTarget = figures?.targetWeight != null;
+      const drift = figures?.drift != null ? signed(formatAllocationDrift(figures.drift), figures.drift) : hasTarget ? missing : "—";
+      const trade = units == null ? "" : figures?.tradeUnits != null
+        ? signed(formatTradeUnits(figures.tradeUnits, { units, assetCategory }), figures.tradeUnits)
+        : hasTarget ? missing : "—";
+      const tradeValue = figures?.tradeValue != null ? signed(wholeMoney(figures.tradeValue, { signed: true }), figures.tradeValue) : hasTarget ? missing : "—";
+      return [weight, target, drift, trade, tradeValue];
+    };
+
+    const rows: string[][] = valued.map(({ ticker, quote, activeQuote, position, metrics, pnl, row }, index) => {
       const priceText = quote && activeQuote
         ? colorBySign(formatMarketPriceWithCurrency(activeQuote.price, quote.currency, priceFormatOptions(quote, ticker.metadata.assetCategory)), activeQuote.change)
         : "—";
       const changeText = activeQuote ? colorBySign(formatPercentRaw(activeQuote.changePercent), activeQuote.change) : "—";
-      if (!position || !metrics) return [ticker.metadata.ticker, priceText, changeText, "—", "—", "—"];
+      const exported = positionsExport[index]!;
+      const figures = exported.weight != null || exported.targetWeight != null || exported.tradeValue != null
+        ? { weight: exported.weight, targetWeight: exported.targetWeight, drift: exported.drift, tradeValue: exported.tradeValue, tradeUnits: exported.tradeShares }
+        : undefined;
+      const symbolUnits = allocationBySymbol.get(ticker.metadata.ticker)?.units ?? 0;
+      if (!position || !metrics) {
+        return [ticker.metadata.ticker, priceText, changeText, "—", "—", "—",
+          ...allocationCells(figures, { unpriced: false, units: symbolUnits, assetCategory: ticker.metadata.assetCategory }), "—"];
+      }
       const positionCurrency = metrics.positionCurrency;
+      const marketValue = row.marketValue as number | null;
+      const unpriced = marketValue == null;
       return [
         ticker.metadata.ticker,
         priceText,
         changeText,
         formatMarketQuantity(metrics.totalShares, { assetCategory: ticker.metadata.assetCategory, multiplier: position.multiplier, priceBasis: metrics.priceBasis, quantityCurrency: positionCurrency }),
         formatMarketCostWithCurrency(position.avgCost, positionCurrency, { assetCategory: ticker.metadata.assetCategory, multiplier: position.multiplier, priceBasis: metrics.priceBasis }),
-        pnl == null || !Number.isFinite(pnl) ? "—" : colorBySign(formatSignedCurrency(pnl, currency), pnl),
+        unpriced ? NOT_AVAILABLE : wholeMoney(marketValue),
+        ...allocationCells(figures, { unpriced, units: symbolUnits, assetCategory: ticker.metadata.assetCategory }),
+        pnl == null || !Number.isFinite(pnl) ? "—" : colorBySign(money(pnl, { signed: true }), pnl),
       ];
     });
-
-    const accountingBasis = "Unrealized P&L on current positions; excludes realized trades, distributions and cash flows. This is not account investment return.";
-    const manualAccounting = !matchedPortfolio?.brokerId && !matchedPortfolio?.brokerInstanceId
-      ? "Manual holdings are snapshots. Reconcile shares and per-share cost after corporate actions using portfolio position set; cash distributions are not credited."
-      : null;
-    if (structured) {
-      ctx.printResult({ data: positionsExport, metadata: {
-        portfolioId: id, portfolioName: displayName, baseCurrency: currency,
-        totalUnrealizedPnl: unavailablePnl.size > 0 ? null : totalPnl,
-        complete: unavailablePnl.size === 0 && unavailableCost.size === 0 && unavailableMarketValue.size === 0,
-        unavailableSymbols: [...new Set([...unavailablePnl, ...unavailableCost, ...unavailableMarketValue])],
-        unavailableCostSymbols: [...unavailableCost], brokerPnlSymbols: [...brokerPnlSymbols],
-        accountingBasis, ...(manualAccounting ? { manualAccounting } : {}),
-      } });
-      return;
+    if (cashExport) {
+      const label = cashExport.currency && cashExport.currency !== currency ? `${CASH_SYMBOL} ${cashExport.currency}` : CASH_SYMBOL;
+      rows.push([label, "", "", "", "", cashExport.value == null ? NOT_AVAILABLE : wholeMoney(cashExport.value),
+        ...allocationCells(cashExport, { unpriced: cashExport.value == null }), ""]);
     }
+    const total = allocation.total;
+    rows.push([
+      cliStyles.bold("TOTAL"), "", "", "", "",
+      cliStyles.bold(wholeMoney(total)),
+      total != null && total > 0 ? formatAllocationWeight(100) : "—",
+      ...(showTargets ? [formatAllocationWeight(allocation.targetSum), "", "", ""] : []),
+      totalPnlValue == null ? "—" : colorBySign(money(totalPnlValue, { signed: true }), totalPnlValue),
+    ]);
 
+    const quantityHeader = filtered.some(ticker => ticker.metadata.assetCategory?.toUpperCase() === "BOND") || positionsExport.some(row => row.quantityUnit === "face") ? "Qty" : "Shares";
+    // A narrow terminal drops the cost, then the quote, then P&L, before any of the allocation.
     console.log(renderTable(
       [
         { header: "Ticker" },
-        { header: "Last", align: "right" },
-        { header: "Chg", align: "right" },
-        { header: filtered.some(ticker => ticker.metadata.assetCategory?.toUpperCase() === "BOND") || positionsExport.some(row => row.quantityUnit === "face") ? "Qty" : "Shares", align: "right" },
-        { header: "Avg Cost", align: "right" },
-        { header: "P&L", align: "right" },
+        { header: "Last", align: "right", optional: true, dropPriority: 1 },
+        { header: "Chg", align: "right", optional: true, dropPriority: 2 },
+        { header: quantityHeader, align: "right" },
+        { header: "Avg Cost", align: "right", optional: true, dropPriority: 3 },
+        { header: "Value", align: "right" },
+        { header: "Weight", align: "right" },
+        ...(showTargets
+          ? [
+            { header: "Target", align: "right" as const },
+            { header: "Drift", align: "right" as const },
+            { header: "Trade", align: "right" as const },
+            { header: "Trade Value", align: "right" as const },
+          ]
+          : []),
+        { header: "P&L", align: "right", optional: true },
       ],
       rows,
     ));
     console.log("");
-    console.log(renderStats([[brokerPnlSymbols.size ? "Total P&L (incl. broker snapshots)" : "Total P&L", unavailablePnl.size > 0 ? "—" : colorBySign(formatSignedCurrency(totalPnl, currency), totalPnl)]]));
-    if (unavailableCost.size > 0) console.log(cliStyles.muted(`Cost unavailable for ${[...unavailableCost].join(", ")}.`));
-    if (unavailablePnl.size > 0) console.log(cliStyles.muted(`P&L unavailable for ${[...unavailablePnl].join(", ")}.`));
+    const notes: string[] = [];
+    if (allocation.unpriced.length > 0) {
+      const count = allocation.unpriced.length;
+      notes.push(cliStyles.warning(`Total and weights exclude ${count} unpriced holding${count === 1 ? "" : "s"}: ${allocation.unpriced.join(", ")}.`));
+    }
+    if (cashExport?.source === "broker") notes.push(cliStyles.muted("Cash is the broker account's balance as of its last sync."));
+    if (matchedPortfolio.brokerInstanceId && !account) notes.push(cliStyles.warning(BROKER_ACCOUNT_MISSING_NOTE));
+    if (cashExport && cashExport.value == null) {
+      notes.push(cliStyles.warning(cashExport.currency
+        ? `No ${cashExport.currency}/${currency} rate for the cash, so the total and weights are unavailable.`
+        : "The cash's currency is unknown, so the total and weights are unavailable."));
+    }
+    const targetNote = describeTargetSum(allocation.targetSum);
+    if (targetNote) notes.push(cliStyles.muted(targetNote));
+    if (brokerPnlSymbols.size > 0) notes.push(cliStyles.muted(`P&L for ${[...brokerPnlSymbols].join(", ")} is the broker's last snapshot.`));
+    if (unavailableCost.size > 0) notes.push(cliStyles.muted(`Cost unavailable for ${[...unavailableCost].join(", ")}.`));
+    if (unavailablePnl.size > 0) notes.push(cliStyles.muted(`P&L unavailable for ${[...unavailablePnl].join(", ")}.`));
+    for (const note of notes) console.log(note);
   } else {
     const rows: string[][] = [];
     for (const ticker of filtered) {
@@ -359,5 +552,5 @@ async function showCollectionWithMarketData(
       rows,
     ));
   }
-
+  if (freshness) console.log(`\n${cliFreshnessFooter(freshness)}`);
 }

package/src/plugins/builtin/portfolio-list/cli/shared.ts

@@ -1,5 +1,32 @@
 import type { AppConfig } from "../../../../types/config";
+import type { CliCommandContext } from "../../../../types/plugin";
+import type { TickerRecord } from "../../../../types/ticker";
+import { parseListingArg, type SavedListingName } from "../../../../cli/listing-arg";
+import { isUsListingExchange } from "../../../../utils/exchanges";
 import { findPortfolio, isManualPortfolio } from "../mutations";
+import { CASH_SYMBOL } from "../allocation";
+
+/** A command error with a hint printed under it. */
+export class PortfolioCliError extends Error {
+  constructor(message: string, readonly details?: string) {
+    super(message);
+    this.name = "PortfolioCliError";
+  }
+}
+
+/** Fails the command with the error's message and hint, or the fallback for anything unexpected. */
+export function failPortfolioCommand(ctx: CliCommandContext, error: unknown, fallback: string): never {
+  if (error instanceof Error) {
+    const details = (error as { details?: unknown }).details;
+    return ctx.fail(error.message, typeof details === "string" ? details : undefined);
+  }
+  return ctx.fail(fallback);
+}
+
+/** What add and remove report about the listing they changed, as JSON and as the sentence's subject. */
+export function listingFields(saved: SavedListingName) {
+  return { listing: saved.key, symbol: saved.symbol, exchange: saved.exchange || null, name: saved.name };
+}
 
 export function parseFiniteNumber(rawValue: string | undefined, label: string): number {
   const value = Number(rawValue);
@@ -9,13 +36,51 @@ export function parseFiniteNumber(rawValue: string | undefined, label: string):
   return value;
 }
 
-export function requireManualPortfolio(config: AppConfig, rawName: string): NonNullable<ReturnType<typeof findPortfolio>> {
+export function requirePortfolio(config: AppConfig, rawName: string): NonNullable<ReturnType<typeof findPortfolio>> {
   const portfolio = findPortfolio(config, rawName);
   if (!portfolio) {
-    throw new Error(`Portfolio "${rawName}" was not found.`);
+    throw new PortfolioCliError(
+      `Portfolio "${rawName}" was not found.`,
+      config.portfolios.length > 0 ? `Portfolios: ${config.portfolios.map((entry) => entry.name).join(", ")}` : undefined,
+    );
   }
+  return portfolio;
+}
+
+export function requireManualPortfolio(config: AppConfig, rawName: string): NonNullable<ReturnType<typeof findPortfolio>> {
+  const portfolio = requirePortfolio(config, rawName);
   if (!isManualPortfolio(portfolio)) {
     throw new Error(`Portfolio "${portfolio.name}" is broker-managed and cannot be modified manually.`);
   }
   return portfolio;
 }
+
+/** Whether the argument is the bare cash line rather than a listing (`CASH:NASDAQ` is a stock). */
+export function isCashArgument(symbol: string, exchange?: string): boolean {
+  const listing = parseListingArg(symbol, exchange);
+  return listing.symbol === CASH_SYMBOL && !listing.exchange;
+}
+
+/**
+ * Bare `CASH` would resolve to a company that trades under that symbol and
+ * value the cash as its shares. Cash has its own line.
+ */
+export function rejectCashSymbol(symbol: string, exchange: string | undefined, portfolioName: string): void {
+  if (!isCashArgument(symbol, exchange)) return;
+  throw new PortfolioCliError(
+    "CASH is the portfolio's cash line, not a ticker.",
+    `Record cash with: gloomberb portfolio cash set "${portfolioName}" <amount> [currency]. For the stock that trades as CASH, name its exchange: CASH:NASDAQ.`,
+  );
+}
+
+/** `VTI (Vanguard Total Stock Market ETF)`, with the venue and currency for a listing outside the US. */
+export function describeTicker(ticker: TickerRecord): string {
+  const { ticker: symbol, name, exchange, currency } = ticker.metadata;
+  const foreign = !!exchange && !isUsListingExchange(exchange);
+  const details = [
+    name?.trim(),
+    foreign ? exchange : undefined,
+    foreign && currency && currency.toUpperCase() !== "USD" ? currency.toUpperCase() : undefined,
+  ].filter((part): part is string => !!part);
+  return details.length > 0 ? `${symbol} (${details.join(", ")})` : symbol;
+}

package/src/plugins/builtin/portfolio-list/cli/watchlist-command.ts

@@ -3,6 +3,8 @@ import { withConfigData, withMarketData } from "../../../../cli/scoped-context";
 import { countCollectionTickers, findWatchlist } from "../../../../cli/helpers";
 import { slugifyName } from "../../../../utils/slugify";
 import { resolveTickerForCli } from "../../../../cli/ticker-resolution";
+import { takeOption } from "../../../../cli/commands/command-utils";
+import { EXCHANGE_OPTION, loadSavedListing, requireListingArg, savedListingName } from "../../../../cli/listing-arg";
 import {
   cliStyles,
   renderSection,
@@ -10,9 +12,13 @@ import {
   renderTable,
 } from "../../../../utils/cli-output";
 import type { CliCommandContext, CliCommandDef } from "../../../../types/plugin";
-import type { TickerRecord } from "../../../../types/ticker";
-import { addTickerToWatchlist, deleteWatchlist as deleteWatchlistConfig } from "../mutations";
+import {
+  addTickerToWatchlist,
+  deleteWatchlist as deleteWatchlistConfig,
+  removeTickerFromWatchlist as removeWatchlistMembership,
+} from "../mutations";
 import { showCollection } from "./render";
+import { listingFields } from "./shared";
 import { CLI_COMMAND_GROUPS } from "../../../../cli/help";
 
 async function createWatchlist(name: string, ctx: CliCommandContext) {
@@ -52,52 +58,47 @@ async function deleteWatchlist(name: string, ctx: CliCommandContext) {
   });
 }
 
-async function addTickerToWatchlistCommand(watchlistName: string, symbol: string, ctx: CliCommandContext) {
+async function addTickerToWatchlistCommand(watchlistName: string, symbol: string, exchange: string | undefined, ctx: CliCommandContext) {
   await withMarketData(ctx, async ({ config, store, dataProvider }) => {
     const watchlist = findWatchlist(config, watchlistName);
     if (!watchlist) ctx.fail(`Watchlist "${watchlistName}" was not found.`);
 
     try {
-      const ticker = await resolveTickerForCli(symbol, store, dataProvider);
+      const ticker = await resolveTickerForCli(symbol, store, dataProvider, exchange);
       const result = addTickerToWatchlist(ticker, watchlist.id);
+      // Name the listing that was stored: SAN:EPA is not the SAN that a bare SAN means.
+      const saved = savedListingName(ticker);
+      const data = { changed: result.changed, ...listingFields(saved), watchlist: watchlist.name };
       if (!result.changed) {
-        console.log(cliStyles.warning(`${ticker.metadata.ticker} is already in "${watchlist.name}".`));
+        ctx.printResult({ data }, { text: () => cliStyles.warning(`${saved.label} is already in "${watchlist.name}".`) });
         return;
       }
 
-      const nextTicker = result.ticker;
-      await store.saveTicker(nextTicker);
-      console.log(cliStyles.success(`Added ${nextTicker.metadata.ticker} to "${watchlist.name}".`));
-      if (nextTicker.metadata.name) {
-        console.log(renderStats([["Name", nextTicker.metadata.name]]));
-      }
+      await store.saveTicker(result.ticker);
+      ctx.printResult({ data }, { text: () => cliStyles.success(`Added ${saved.label} to "${watchlist.name}".`) });
     } catch (error) {
       ctx.fail(error instanceof Error ? error.message : `Failed to add ${symbol} to "${watchlist.name}".`);
     }
   });
 }
 
-async function removeTickerFromWatchlist(watchlistName: string, symbol: string, ctx: CliCommandContext) {
+async function removeTickerFromWatchlist(watchlistName: string, symbol: string, exchange: string | undefined, ctx: CliCommandContext) {
+  // SAN:EPA and SAN --exchange EPA name the stored listing, which a bare SAN may hold under another venue.
+  const listing = await requireListingArg(symbol, exchange, ctx);
   await withConfigData(ctx, async ({ config, store }) => {
     const watchlist = findWatchlist(config, watchlistName);
     if (!watchlist) ctx.fail(`Watchlist "${watchlistName}" was not found.`);
 
-    const normalized = symbol.trim().toUpperCase();
-    const ticker = await store.loadTicker(normalized);
-    if (!ticker) ctx.fail(`Ticker "${normalized}" was not found in your local data.`);
-    if (!ticker.metadata.watchlists.includes(watchlist.id)) {
-      ctx.fail(`${normalized} is not in "${watchlist.name}".`);
-    }
+    const ticker = await loadSavedListing(store, listing);
+    if (!ticker) ctx.fail(`Ticker "${listing.key}" was not found in your local data.`);
+    const saved = savedListingName(ticker);
+    const result = removeWatchlistMembership(ticker, watchlist.id);
+    if (!result.changed) ctx.fail(`${saved.key} is not in "${watchlist.name}".`);
 
-    const nextTicker: TickerRecord = {
-      ...ticker,
-      metadata: {
-        ...ticker.metadata,
-        watchlists: ticker.metadata.watchlists.filter((entry) => entry !== watchlist.id),
-      },
-    };
-    await store.saveTicker(nextTicker);
-    console.log(cliStyles.success(`Removed ${normalized} from "${watchlist.name}".`));
+    await store.saveTicker(result.ticker);
+    ctx.printResult({ data: { changed: true, ...listingFields(saved), watchlist: watchlist.name } }, {
+      text: () => cliStyles.success(`Removed ${saved.label} from "${watchlist.name}".`),
+    });
   });
 }
 
@@ -156,9 +157,12 @@ export const watchlistCliCommand: CliCommandDef = {
       "watchlist add <watchlist> <symbol>",
       "watchlist remove <watchlist> <symbol>",
     ],
-    examples: ["watchlist show Growth", "watchlist create Growth", "watchlist add Growth NVDA"],
+    options: [EXCHANGE_OPTION],
+    examples: ["watchlist show Growth", "watchlist create Growth", "watchlist add Growth NVDA", "watchlist add Growth SAN:EPA"],
   },
-  execute: async (args, ctx) => {
+  execute: async (rawArgs, ctx) => {
+    const args = [...rawArgs];
+    const exchange = takeOption(args, "--exchange");
     const action = args[0];
 
     if (!action || action === "list") {
@@ -191,7 +195,7 @@ export const watchlistCliCommand: CliCommandDef = {
       const symbol = args.at(-1);
       const name = args.slice(1, -1).join(" ");
       if (!name || !symbol) ctx.fail("Usage: gloomberb watchlist add <watchlist> <ticker>");
-      await addTickerToWatchlistCommand(name!, symbol!, ctx);
+      await addTickerToWatchlistCommand(name!, symbol!, exchange, ctx);
       return;
     }
 
@@ -199,7 +203,7 @@ export const watchlistCliCommand: CliCommandDef = {
       const symbol = args.at(-1);
       const name = args.slice(1, -1).join(" ");
       if (!name || !symbol) ctx.fail("Usage: gloomberb watchlist remove <watchlist> <ticker>");
-      await removeTickerFromWatchlist(name!, symbol!, ctx);
+      await removeTickerFromWatchlist(name!, symbol!, exchange, ctx);
       return;
     }