gloomberb 0.18.0 → 0.18.1

package/src/plugins/builtin/notes/files.ts

@@ -35,6 +35,13 @@ export interface NotesFilesIO {
 }
 
 const QUICK_NOTES_INDEX_FILE = "__quick-notes-index__.json";
+
+export interface NotesListOptions {
+  /** A notes folder that cannot be listed rejects instead of listing nothing. */
+  strict?: boolean;
+  /** Hears each note left out because it could not be read, for a caller that says so. */
+  skipped?: (key: string, error: unknown) => void;
+}
 const LOCAL_KEY_PREFIX = "gloomberb:notes:";
 const LOCAL_TIMESTAMP_KEY = "gloomberb:notes:__updated-at__";
 
@@ -237,8 +244,8 @@ export class NotesFiles implements NotesStore {
   }
 
   /** Every stored note, ticker notes and quick notes alike, newest first. */
-  async list(): Promise<NoteFileEntry[]> {
-    const { entries } = await this.readEach(await this.io.listKeys());
+  async list(options: NotesListOptions = {}): Promise<NoteFileEntry[]> {
+    const { entries } = await this.readEach(await this.io.listKeys({ strict: options.strict }), options.skipped);
     return entries.sort((left, right) => right.updatedAt - left.updatedAt);
   }
 
@@ -277,7 +284,10 @@ export class NotesFiles implements NotesStore {
   }
 
   /** An unreadable note is left out and counted rather than synced as empty. */
-  private async readEach(keys: Array<[string, number]>): Promise<{ entries: NoteFileEntry[]; unreadable: number }> {
+  private async readEach(
+    keys: Array<[string, number]>,
+    skipped?: NotesListOptions["skipped"],
+  ): Promise<{ entries: NoteFileEntry[]; unreadable: number }> {
     const entries: NoteFileEntry[] = [];
     let unreadable = 0;
     for (const [key, updatedAt] of keys) {
@@ -286,6 +296,7 @@ export class NotesFiles implements NotesStore {
       } catch (error) {
         unreadable += 1;
         logFailure("notes.files", "Read a note while listing notes failed")(error);
+        skipped?.(key, error);
       }
     }
     return { entries, unreadable };

package/src/plugins/builtin/notes/index.tsx

@@ -2,7 +2,7 @@ import { apiClient } from "../../../api-client";
 import type { GloomPlugin } from "../../../types/plugin";
 import { teamStore } from "../../../team/store";
 import { notesCliCommand } from "./cli";
-import { exportNotesToDirectory, exportSourceLabel } from "./export";
+import { exportNotesToDirectory, exportNotice, exportSourceLabel } from "./export";
 import { NotesFiles } from "./files";
 import { migrateLocalNotes, notesMigratedAt } from "./migration";
 import { createQuickNotesPane } from "./quick-notes-pane";
@@ -114,8 +114,8 @@ export const notesPlugin: GloomPlugin = {
           ...teams.map((team) => ({ label: exportSourceLabel(registry.forOwner({ kind: "team", teamId: team.id }), team.name), store: registry.forOwner({ kind: "team", teamId: team.id }) })),
         ];
         try {
-          const result = await exportNotesToDirectory(dir, sources);
-          ctx.notify({ body: `Exported ${result.files} ${result.files === 1 ? "note" : "notes"} to ${result.dir}`, type: "success" });
+          // What was skipped is said with the count, as `notes export` warns.
+          ctx.notify(exportNotice(await exportNotesToDirectory(dir, sources)));
         } catch (error) {
           ctx.notify({ body: error instanceof Error ? error.message : "Could not export notes.", type: "error" });
         }

package/src/plugins/builtin/notes/quick-notes-pane.tsx

@@ -59,6 +59,9 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
     const lastSavedTextRef = useRef<Map<string, string>>(new Map());
     const loadedTabIdRef = useRef<string | null>(null);
     const loadedRef = useRef(false);
+    // Owners whose index exists but could not be read: nothing is saved over it.
+    const unreadableIndexRef = useRef(new Set<string>());
+    const [indexError, setIndexError] = useState<{ message: string; owners: NoteOwner[] } | null>(null);
     const activeTab = tabs.find((tab) => tab.id === activeTabId);
 
     const saveQuickNotesIndex = useCallback((entries: OwnedQuickNote[]) => {
@@ -73,7 +76,7 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
       for (const owner of owners) {
         const bucket = byOwner.get(noteOwnerKey(owner));
         const store = storeFor(owner);
-        if (store.readOnly) continue;
+        if (store.readOnly || unreadableIndexRef.current.has(noteOwnerKey(owner))) continue;
         store.saveQuickNotesIndex(bucket?.entries ?? []).catch((error) => {
           notesLog.error("Failed to save notes index", { error: error instanceof Error ? error.message : String(error) });
           notify({ body: error instanceof Error ? error.message : "Failed to save notes index.", type: "error" });
@@ -143,17 +146,24 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
     useEffect(() => {
       // Mine first, then each team's notes; reloads when the team list changes.
       let cancelled = false;
+      const unreadable = new Map<string, { owner: NoteOwner; message: string }>();
       void Promise.all(owners.map(async (owner) => {
         try {
-          return (await storeFor(owner).loadQuickNotesIndex()).map((entry) => ({ ...entry, owner }));
+          return (await storeFor(owner).loadQuickNotesIndex({ strict: true })).map((entry) => ({ ...entry, owner }));
         } catch (error) {
+          unreadable.set(noteOwnerKey(owner), { owner, message: error instanceof Error ? error.message : String(error) });
           return logFailure("notes.quick-notes", "Load a quick notes index failed", [] as OwnedQuickNote[])(error);
         }
       })).then((lists) => {
         if (cancelled) return;
+        unreadableIndexRef.current = new Set(unreadable.keys());
+        const failed = [...unreadable.values()];
+        setIndexError(failed.length > 0 ? { message: failed[0]!.message, owners: failed.map((entry) => entry.owner) } : null);
         const entries = lists.flat();
         if (entries.length === 0) {
-          if (loadedRef.current) return;
+          // Only a first run, with no index yet, gets a first tab; an index
+          // that failed to load must not have a fresh one saved over it.
+          if (loadedRef.current || unreadable.size > 0) return;
           const id = generateNoteId();
           const initial: OwnedQuickNote[] = [{ id, title: "New", owner: { kind: "user" } }];
           lastSavedTextRef.current.set(id, "");
@@ -224,6 +234,10 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
         notify({ body: `${ownerLabel(owner, teams)} notes are read-only right now.`, type: "info" });
         return;
       }
+      if (unreadableIndexRef.current.has(noteOwnerKey(owner))) {
+        notify({ body: `${ownerLabel(owner, teams)} quick notes could not be read, so a new one is not added yet.`, type: "info" });
+        return;
+      }
       const id = generateNoteId();
       const entry: OwnedQuickNote = { id, title: "New", owner };
       lastSavedTextRef.current.set(id, "");
@@ -243,6 +257,14 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
       const owner = tabOwner(id, tabsRef.current);
       setTabs((prev) => {
         const next = prev.filter((t) => t.id !== id);
+        // With my index unreadable, a fresh tab of mine could not be saved in it.
+        if (next.length === 0 && unreadableIndexRef.current.has(noteOwnerKey({ kind: "user" }))) {
+          saveQuickNotesIndex(next);
+          setActiveTabId(null);
+          setNoteText("");
+          prevTabRef.current = null;
+          return next;
+        }
         if (next.length === 0) {
           const newId = generateNoteId();
           const fresh: OwnedQuickNote[] = [{ id: newId, title: "New", owner: { kind: "user" } }];
@@ -332,6 +354,13 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
       if (activeTabId) void requestRemoveTab(activeTabId);
     }, [activeTabId, requestRemoveTab]);
 
+    // With no tab to show, an index that failed to load is the pane's state;
+    // beside other owners' tabs it is a footer warning.
+    const indexUnreadable = tabs.length === 0 && !!indexError;
+    const readError = loadError ?? (indexUnreadable ? indexError!.message : null);
+    const footerWarning = readError
+      ?? (indexError ? `${indexError.owners.map((owner) => ownerLabel(owner, teams)).join(", ")} quick notes could not be read` : null);
+
     // n, t and d are footer hints, which bind them without modifiers, so the
     // shell's Ctrl+W or Cmd+N never adds or deletes a note.
     useShortcut((event) => {
@@ -351,7 +380,7 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
       }
 
       // A note that failed to load stays read-only, as it does for a click.
-      if (isPlainKey(event, "enter", "return") && !editing && !loadError) {
+      if (isPlainKey(event, "enter", "return") && !editing && !readError) {
         event.preventDefault();
         setEditing(true);
         return;
@@ -375,11 +404,11 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
 
     // Deleting the only note when it is empty just swaps in another empty one,
     // and a note that failed to load reads as empty, so it would go unconfirmed.
-    const canDelete = !!activeTabId && !loadError && (tabs.length > 1 || noteText.trim().length > 0);
+    const canDelete = !!activeTabId && !readError && (tabs.length > 1 || noteText.trim().length > 0);
 
     usePaneFooter("quick-notes", () => ({
-      info: loadError
-        ? [{ id: "load-error", parts: [{ text: loadError, tone: "warning" as const }] }]
+      info: footerWarning
+        ? [{ id: "load-error", parts: [{ text: footerWarning, tone: "warning" as const }] }]
         : [
             { id: "edited", parts: [{ text: editing || renaming ? "editing" : formatLastEdited(activeTab?.updatedAt), tone: "muted" as const }] },
           ],
@@ -391,7 +420,7 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
             { id: "title", key: "t", label: "itle", title: "Rename Note", onPress: startRename, disabled: !activeTabId },
             { id: "delete", key: "d", label: "elete", title: "Delete Note", onPress: deleteActiveNote, disabled: !canDelete },
           ],
-    }), [activeTab, activeTabId, addTab, canDelete, deleteActiveNote, editing, loadError, renaming, startRename]);
+    }), [activeTab, activeTabId, addTab, canDelete, deleteActiveNote, editing, footerWarning, renaming, startRename]);
 
     const noteTabs = tabs.map((tab) => ({
       label: tab.owner.kind === "team" ? `${ownerLabel(tab.owner, teams)} ${tab.title}` : tab.title,
@@ -437,13 +466,19 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
             />
           </Box>
         )}
-        <Box flexGrow={1} minHeight={0} paddingX={1} onMouseDown={() => { if (!editing && !renaming && !loadError) setEditing(true); }}>
+        <Box flexGrow={1} minHeight={0} paddingX={1} onMouseDown={() => { if (!editing && !renaming && !readError) setEditing(true); }}>
           {loadError ? (
             <EmptyState
               title="This note could not be read."
               message={loadError}
               hint="Editing is disabled so the saved note is not overwritten. Fix the file, then reopen the pane."
             />
+          ) : indexUnreadable ? (
+            <EmptyState
+              title="Quick notes could not be read."
+              message={indexError!.message}
+              hint="Nothing is saved over them until they load. Reopen the pane to try again."
+            />
           ) : editing && !renaming ? (
             <MarkdownEditor
               textareaKey="editing"
@@ -458,7 +493,7 @@ export function createQuickNotesPane(registry: NotesStoreRegistry) {
               text={noteText}
               width={width}
               placeholder="Write notes..."
-              onActivate={() => { if (!renaming && !loadError) setEditing(true); }}
+              onActivate={() => { if (!renaming && !readError) setEditing(true); }}
             />
           )}
         </Box>

package/src/plugins/builtin/notes/store.ts

@@ -7,7 +7,7 @@ import {
   type NoteKind,
 } from "../../../api-client";
 import type { PluginPersistence } from "../../../types/plugin";
-import type { NoteFileEntry, QuickNoteEntry } from "./files";
+import type { NoteFileEntry, NotesListOptions, QuickNoteEntry } from "./files";
 
 export { NoteConflictError };
 
@@ -27,8 +27,18 @@ export interface NotesStore {
   load(key: string): Promise<string>;
   save(key: string, text: string, options?: { title?: string | null }): Promise<void>;
   delete(key: string): Promise<void>;
-  list(): Promise<NoteFileEntry[]>;
-  loadQuickNotesIndex(): Promise<QuickNoteEntry[]>;
+  /**
+   * Every note, newest first. A note that cannot be read is left out and
+   * handed to `skipped`; with `strict`, notes that cannot be listed at all
+   * reject instead of coming back as none.
+   */
+  list(options?: NotesListOptions): Promise<NoteFileEntry[]>;
+  /**
+   * The quick notes' ids and titles. With `strict`, an index that exists but
+   * cannot be read rejects instead of reading as empty, for a caller that
+   * would otherwise save a replacement over it.
+   */
+  loadQuickNotesIndex(options?: { strict?: boolean }): Promise<QuickNoteEntry[]>;
   saveQuickNotesIndex(entries: QuickNoteEntry[]): Promise<void>;
   quickNoteKey(id: string): string;
   /** Called after a server-side change so the next load sees it. */

package/src/plugins/builtin/portfolio-list/cli/bulk-symbols.ts

@@ -37,7 +37,7 @@ export const FILE_OPTION = {
 export const SYMBOL_LIST_HELP = {
   title: "Several symbols",
   lines: [
-    "add and remove take any number of symbols split by spaces, commas or newlines, a --file, or piped input (or -). An entry of a list with commas or newlines that has spaces in it is a company's name when search finds one, read as its US listing first with a line under it saying which, and otherwise the symbols it holds. A CSV is read from its Symbol, Ticker or Code column, else its first. Quote a list name with spaces.",
+    "add and remove take any number of symbols split by spaces, commas or newlines, a --file, or piped input (or -). An entry of a list with commas or newlines that has spaces in it is a company's name when search finds one, read as its US listing first with a line under it saying which, and otherwise the symbols it holds. A CSV is read from its Symbol, Ticker or Code column. Without that header every cell is a symbol, unless names, prices or weights sit beside them: then the first column is read and the cells left out are named. Quote a list name with spaces.",
     "Each symbol gets a line, then a summary. Exit status 0 when at least one symbol was added (or removed) or already was, 1 when none resolved or the usage is wrong.",
     "A bare US-style symbol is not added when the listing it matched stopped trading, is abroad (DFS as DFS:LSE) or was taken by another company in the last two years (BRKL), or when nothing lists under it now and its company trades as another. Those are listed under Needs a choice, with the add for what their company trades as now and the listing that matched, which naming keeps; one symbol alone fails with the same. A symbol another company took longer ago says so under its line.",
     "add --dry-run looks every symbol up and prints the same lines without saving.",
@@ -115,14 +115,15 @@ interface CollectionRef {
 /**
  * One line per symbol and the summary under them; `--json` and `--csv` give
  * the rows, with the summary in the JSON metadata and on standard error beside
- * CSV. A separator dropped from a symbol of the list is named as a warning. The
- * command exits non-zero when no symbol ended up as asked.
+ * CSV. A separator dropped from a symbol of the list, and the cells a table
+ * read by one column left out, are named as warnings. The command exits
+ * non-zero when no symbol ended up as asked.
  */
 export function printSymbolRows(
   ctx: CliCommandContext,
   rows: SymbolRow[],
-  { verb, collection, repeated, strays, retry, dryRun = false }: {
-    verb: Verb; collection: CollectionRef; repeated: number; strays: readonly string[];
+  { verb, collection, repeated, notes, retry, dryRun = false }: {
+    verb: Verb; collection: CollectionRef; repeated: number; notes: readonly string[];
     /** The add of some listings, for the line that adds what the symbols needing a choice trade as now. */
     retry?: (keys: string) => string;
     dryRun?: boolean;
@@ -137,7 +138,7 @@ export function printSymbolRows(
   ctx.printResult({
     data: rows,
     metadata: { [collection.kind]: collection.name, ...counts, repeated, summary, ...dryRun ? { dryRun } : {} },
-    ...strays.length > 0 ? { warnings: [...strays] } : {},
+    ...notes.length > 0 ? { warnings: [...notes] } : {},
   }, {
     text: () => [
       ...rows.filter((row) => row.status !== "needs_choice").map((row) => rowLines(row, verb)),
@@ -215,7 +216,7 @@ export async function requireSymbolList(
   file: string | undefined,
   usage: string,
   readEntries?: (entries: string[]) => Promise<string[]>,
-): Promise<{ symbols: string[]; repeated: number; strays: string[]; single: string | null }> {
+): Promise<{ symbols: string[]; repeated: number; notes: string[]; single: string | null }> {
   try {
     let typed: string[] = [];
     const list = await readSymbolList({ args, file, readEntries: async (entries) => {

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

@@ -47,7 +47,14 @@ import { importSource, notionalPositions, rankThirteenFLines, type ThirteenFImpo
 import { importedFromText } from "../imported-from";
 import { savedListingCoinNote } from "../../../../cli/commands/crypto-hints";
 import { findNamedCollection } from "../../../../portfolio/collection-name";
-import { parseTypedNumber, readCurrencyAmount } from "../../../../utils/decimal-comma";
+import { wholeUnitQuantityProblem } from "../../../../portfolio/position-quantity";
+import { CostFxError, loadCostFxRate, type CostFxHistoryClient } from "../../../../portfolio/cost-fx";
+import { lotCostFxRate, sameCurrency } from "../../../../portfolio/position-metrics";
+import { formatFxRate } from "../../../../cli/fx-pair";
+import { createBaseConverter } from "../../../../cli/base-converter";
+import { currencyUnitLabel, heldCurrencyUnit } from "../../../../utils/currency-units";
+import { parseTypedNumber, readCurrencyAmount, readTypedNumber } from "../../../../utils/decimal-comma";
+import { DATE_OPTION_EXAMPLES, dateOptionError, readCalendarDate } from "../../../../utils/calendar-date";
 import {
   failPortfolioCommand,
   isCashArgument,
@@ -66,6 +73,7 @@ import { readNameEntries } from "../../../../cli/name-entries";
 import { DRIP_DEFAULT_YEARS, DRIP_MAX_YEARS, parseDripYears, parseWithholding } from "../income";
 
 const ADD_USAGE = "Usage: gloomberb portfolio add <portfolio> <symbols...> [--file <path>]";
+const POSITION_USAGE = "Usage: gloomberb portfolio position set <portfolio> <ticker> <shares|contracts> <avg-cost> [currency] [--date <purchase date> | --cost-fx <rate>]";
 const REMOVE_USAGE = "Usage: gloomberb portfolio remove <portfolio> <symbols...> [--file <path>]";
 const CASH_USAGE = "Usage: gloomberb portfolio cash set <portfolio> <amount> [currency] | portfolio cash clear <portfolio>";
 const TARGET_USAGE = "Usage: gloomberb portfolio target set <portfolio> <symbol|CASH> <weight%> | target clear <portfolio> [symbol] | target show <portfolio>";
@@ -207,7 +215,7 @@ async function addToPortfolioCommand(args: string[], file: string | undefined, e
       retry,
       add: (ticker) => addTickerToPortfolio(ticker, portfolio.id),
     });
-    printSymbolRows(ctx, rows, { verb: "add", collection: { kind: "portfolio", name: portfolio.name }, repeated: list.repeated, strays: list.strays, retry, dryRun });
+    printSymbolRows(ctx, rows, { verb: "add", collection: { kind: "portfolio", name: portfolio.name }, repeated: list.repeated, notes: list.notes, retry, dryRun });
   });
 }
 
@@ -274,7 +282,7 @@ async function removeFromPortfolioCommand(args: string[], file: string | undefin
       },
     });
     if (nextConfig !== context.config) await saveConfig(nextConfig);
-    printSymbolRows(ctx, rows, { verb: "remove", collection: { kind: "portfolio", name: portfolio.name }, repeated: list.repeated, strays: list.strays });
+    printSymbolRows(ctx, rows, { verb: "remove", collection: { kind: "portfolio", name: portfolio.name }, repeated: list.repeated, notes: list.notes });
   });
 }
 
@@ -286,6 +294,8 @@ async function setPositionCommand(
   rawCurrency: string | undefined,
   exchange: string | undefined,
   ctx: CliCommandContext,
+  /** `--date` (an ISO day) and `--cost-fx`, read already; the client reads the date's FX closes. */
+  cost: { date?: string; costFx?: number; history?: CostFxHistoryClient } = {},
   futuresTerms?: (symbol: string) => Promise<FuturesContractTermsPayload | null>,
 ) {
   await withMarketData(ctx, async ({ config, store, dataProvider }) => {
@@ -298,31 +308,56 @@ async function setPositionCommand(
       const avgCost = parseAmountArg(avgCostValue, "Average cost");
       // The notes say which listing a bare symbol went to, and that a bare coin ticker is not the coin, as `portfolio add` does.
       const { ticker, notes } = await resolveCliTicker(symbol, store, dataProvider, exchange);
+      // `1.250` on a listing held in whole lots asks which was meant, as `1,250` did above.
+      const lots = wholeUnitQuantityProblem(sharesValue, ticker, { listing: savedListingName(ticker).key });
+      if (lots) throw new PortfolioCliError(lots);
       // A future is held in contracts of the size its terms give, as `quote` states it, and a cost typed as
       // corn is quoted counts cents.
       const future = isFuturesTicker(ticker);
       const size = await loadFuturesEntrySize(ticker, futuresTerms);
       const currency = resolveManualPositionCurrency(rawCurrency, ticker, portfolio, config.baseCurrency, size?.currency);
+      // The first position of an empty manual portfolio sets its currency; the cost converts into the currency
+      // `portfolio show` values the portfolio in once it is set, which is the base currency when that is not USD.
+      const firstPosition = !hasOpenPortfolioPositions(portfolio.id, await store.loadAllTickers());
+      const adopted = firstPosition ? adoptFirstPositionCurrency(config, portfolio.id, currency) : null;
+      const valued = adopted ?? config;
+      const portfolioCurrency = resolvePortfolioTotalsCurrency(
+        valued.portfolios.find((entry) => entry.id === portfolio.id) ?? portfolio, valued.baseCurrency);
+      const toPortfolio = createBaseConverter(dataProvider, heldCurrencyUnit(portfolioCurrency).currency);
+      const costFx = await positionCostFx({
+        ...cost, currency, portfolioCurrency, listing: savedListingName(ticker).key,
+        // Today's rate, in the units the lot is held in: what a typed rate is checked against.
+        todaysRate: async () => (await toPortfolio(1, heldCurrencyUnit(currency).currency))
+          / heldCurrencyUnit(currency).divisor * heldCurrencyUnit(portfolioCurrency).divisor,
+      });
       const result = setManualPortfolioPosition(ticker, portfolio.id, {
         shares,
         avgCost,
         currency,
         ...(size ? { multiplier: size.multiplier } : {}),
+        ...(cost.date ? { dateAcquired: cost.date } : {}),
+        ...(costFx ? { costFx: costFx.costFx } : {}),
       });
-      const multiplier = result.ticker.metadata.positions.find((position) => position.portfolio === portfolio.id)?.multiplier;
+      const lot = result.ticker.metadata.positions.find((position) => position.portfolio === portfolio.id);
+      const multiplier = lot?.multiplier;
       if (future && !multiplier) {
         notes.push(`No contract size is known for ${savedListingName(result.ticker).label}, so its value and P&L are not shown.`);
       }
-      const firstPosition = !hasOpenPortfolioPositions(portfolio.id, await store.loadAllTickers());
       await store.saveTicker(result.ticker);
-      const adopted = firstPosition ? adoptFirstPositionCurrency(config, portfolio.id, currency) : null;
       if (adopted) await saveConfig(adopted);
       const saved = savedListingName(result.ticker);
       const quantity = formatMarketQuantity(shares, { assetCategory: result.ticker.metadata.assetCategory });
+      // A cost in another currency converts at the rate it was bought at when the lot has one, else at today's, and says so.
+      const foreign = !sameCurrency(currency, portfolioCurrency);
+      const boughtRate = lot ? lotCostFxRate(lot, currency, portfolioCurrency) : null;
+      // The purchase date shows where it was given or sets the rate; a lot in the portfolio's currency otherwise prints as it did.
+      const purchaseDate = lot?.dateAcquired && (cost.date || foreign) ? lot.dateAcquired : null;
       ctx.printResult({
         data: {
           changed: true, ...listingFields(saved), portfolio: portfolio.name, shares, avgCost, currency,
           ...(future ? { contractMultiplier: multiplier ?? null, contractSize: size?.size ?? null } : {}),
+          ...(purchaseDate ? { dateAcquired: purchaseDate } : {}),
+          ...(foreign ? { costFxRate: boughtRate, costFxCurrency: portfolioCurrency, costFxDate: costFx?.date ?? null } : {}),
         },
         warnings: notes.length > 0 ? notes : undefined,
       }, {
@@ -334,7 +369,14 @@ async function setPositionCommand(
               : ["Shares", quantity],
             ["Average Cost", formatMarketCostWithCurrency(avgCost, currency, { assetCategory: result.ticker.metadata.assetCategory })],
             ["Currency", currency],
+            ...(purchaseDate ? [["Purchase Date", purchaseDate] as [string, string]] : []),
+            ...(boughtRate !== null
+              ? [["Cost FX", `${formatFxRate(boughtRate)} ${portfolioCurrency} per ${currency}${costFx?.date ? ` (${costFx.date} close)` : ""}`] as [string, string]]
+              : []),
           ]),
+          ...(foreign && boughtRate === null
+            ? [cliStyles.muted(`Cost converted at today's rate into ${portfolioCurrency}; add --date or --cost-fx to use the rate when bought.`)]
+            : []),
         ].join("\n"),
       });
     } catch (error) {
@@ -343,6 +385,102 @@ async function setPositionCommand(
   });
 }
 
+/**
+ * The rate a position's cost was bought at, from `--cost-fx` as typed or from
+ * the FX closes of its `--date`, for a position held in another currency
+ * than the portfolio's; undefined when neither was given or the position is
+ * in the portfolio's currency (a date alone then only dates the lot).
+ * `--cost-fx` on a position in the portfolio's own currency, a typed rate
+ * that reads as a mistake against today's, and a date with no FX close fail
+ * saying what to give instead.
+ */
+async function positionCostFx({ date, costFx, history, currency, portfolioCurrency, listing, todaysRate }: {
+  date?: string; costFx?: number; history?: CostFxHistoryClient; currency: string; portfolioCurrency: string; listing: string;
+  /** Today's rate, one unit of `currency` in `portfolioCurrency`; NaN when it cannot be read. */
+  todaysRate: () => Promise<number>;
+}): Promise<{ costFx: { rate: number; currency: string }; date: string | null } | undefined> {
+  const foreign = !sameCurrency(currency, portfolioCurrency);
+  const insteadHint = `Give the rate it was bought at instead: --cost-fx <${portfolioCurrency} per ${currency}>.`;
+  if (costFx != null) {
+    if (!foreign) {
+      const held = currency === portfolioCurrency ? currency : `${currency}, a unit of ${portfolioCurrency}`;
+      throw new PortfolioCliError(`--cost-fx converts a cost in another currency; ${listing} is held in ${held}, the portfolio's currency.`);
+    }
+    const problem = implausibleCostFx(costFx, await todaysRate().catch(() => Number.NaN), { currency, portfolioCurrency, listing });
+    if (problem) throw new PortfolioCliError(problem, "Or give the purchase --date, and its daily FX close is used.");
+    return { costFx: { rate: costFx, currency: portfolioCurrency }, date: null };
+  }
+  if (!date || !foreign) return undefined;
+  try {
+    const reading = await loadCostFxRate(currency, portfolioCurrency, date, history ?? apiClient);
+    return { costFx: { rate: reading.rate, currency: portfolioCurrency }, date: reading.date };
+  } catch (error) {
+    if (error instanceof CostFxError) {
+      throw new PortfolioCliError(`${error.message}, so the ${currency} cost cannot be converted at the rate of ${date}.`, insteadHint);
+    }
+    // Offline, signed out or a server error: say what was being read, and the way that needs no network.
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new PortfolioCliError(`Could not read the ${currency} and ${portfolioCurrency} FX closes of ${date}: ${reason}.`, insteadHint);
+  }
+}
+
+/** How far from today's rate a typed one may be: a currency that lost 99% since purchase still fits. */
+const COST_FX_MAX_RATIO = 100;
+
+/**
+ * Why a typed `--cost-fx` reads as a mistake against today's rate, else null:
+ * a rate per pound for a lot held in pence, the inverse of the pair (0.0319
+ * for 31.37 TRY per USD), or more than a hundred times off either way. A
+ * rate is only called inverted when today's is far from 1 and the typed one
+ * lies on the other side of it, so EUR per USD near parity is never refused.
+ * Null when today's rate is not known.
+ */
+function implausibleCostFx(
+  rate: number,
+  today: number,
+  { currency, portfolioCurrency, listing }: { currency: string; portfolioCurrency: string; listing: string },
+): string | null {
+  if (!Number.isFinite(today) || today <= 0) return null;
+  const pair = `${portfolioCurrency} per ${currency}`;
+  const typed = formatFxRate(rate);
+  const todays = `today's is ${formatFxRate(today)} ${pair}`;
+  const unit = heldCurrencyUnit(currency);
+  if (unit.divisor !== 1 && rate / today >= unit.divisor / 5 && rate / today <= unit.divisor * 5) {
+    const name = currency.toUpperCase() === "USX" ? "US cents" : currencyUnitLabel(currency).replace(/^\S+ \((.+)\)$/, "$1");
+    return `--cost-fx ${typed} looks like ${portfolioCurrency} per ${unit.currency}; ${listing} is held in ${currency} (${name}), `
+      + `so the rate is ${pair}, 1/${unit.divisor} of that: ${todays}.`;
+  }
+  if ((today >= 3 && rate < 1) || (today <= 1 / 3 && rate > 1)) {
+    return `--cost-fx ${typed} looks inverted: it is the ${portfolioCurrency} paid for one ${currency}, and ${todays}.`;
+  }
+  if (rate / today > COST_FX_MAX_RATIO || today / rate > COST_FX_MAX_RATIO) {
+    return `--cost-fx ${typed} is more than ${COST_FX_MAX_RATIO} times off today's rate (${formatFxRate(today)} ${pair}); check the rate.`;
+  }
+  return null;
+}
+
+/** `--date`: the day the position was bought, as an ISO day, no later than today (UTC). */
+function parsePurchaseDate(value: string, ctx: CliCommandContext): string {
+  const date = readCalendarDate(value);
+  if (!date) ctx.fail(dateOptionError(value, "--date", { subject: "the purchase date" }), POSITION_USAGE);
+  if (date > new Date().toISOString().slice(0, 10)) ctx.fail(`--date ${value.trim()} is after today; it is the day the position was bought.`, POSITION_USAGE);
+  return date;
+}
+
+/** `--cost-fx`: one unit of the position's currency in the portfolio's when it was bought, a positive number (32,15 reads as 32.15). */
+function parseCostFx(value: string, ctx: CliCommandContext): number {
+  let rate = Number.NaN;
+  try {
+    rate = readTypedNumber(value, "--cost-fx");
+  } catch (error) {
+    ctx.fail(error instanceof Error ? error.message : String(error), POSITION_USAGE);
+  }
+  if (!Number.isFinite(rate) || rate <= 0) {
+    ctx.fail(`--cost-fx is the rate the cost was bought at, a positive number such as 32.15 (TRY per USD); got "${value.trim()}".`, POSITION_USAGE);
+  }
+  return rate;
+}
+
 const CURRENCY_CODE = /^[A-Za-z]{3}$/;
 
 /**
@@ -775,6 +913,8 @@ const POSITION_HELP = {
   lines: [
     "position set replaces the portfolio's lots of the symbol with one: a negative size is a short, and 0 is refused (portfolio remove drops the symbol).",
     "A future's size is in contracts, at a price per unit of its contract (GC=F: per troy ounce); the contract size is read from its terms, as quote shows them.",
+    "The cost is in the currency named after it, else the listing's. A holding in another currency than the portfolio's (a US stock in a TRY portfolio) can be entered at its cost in the portfolio's currency (position set Lira BRK-B 10 20310 TRY), so P&L is in what was paid.",
+    "Entered at its cost in its own currency, its P&L converts the cost at today's rate unless --date gives the purchase date, whose daily FX close is used, or --cost-fx gives the rate paid (portfolio currency per unit of the holding's: 32.15 TRY per USD); then the P&L carries the currency's move since. portfolio show names the holdings whose cost converts at today's rate.",
   ],
 };
 
@@ -792,7 +932,7 @@ const AMOUNTS_HELP = {
   lines: [
     "Numbers take either decimal mark: 1.234,5, 1234,5 and 1,234.5 are 1234.5, and 18,50 is 18.5.",
     "Cash and --notional are amounts of a currency (cash in the portfolio's unless named, --notional in USD), so 500,000 and 1.234 are thousands, a third decimal being below a cent. In a currency with three decimals (KWD, BHD, OMR) they could be either, and the command asks which.",
-    "Shares, contracts and average cost read a lone dot as a decimal point (123.456) and ask which a lone comma before three digits meant (1,234).",
+    "Shares, contracts and average cost read a lone dot as a decimal point (123.456) and ask which a lone comma before three digits meant (1,234). On a listing held in whole lots (shares listed outside the US, a future's contracts) a lone dot before three digits (1.250) asks too.",
   ],
 };
 
@@ -811,7 +951,7 @@ export const portfolioCliCommand: CliCommandDef = {
       "portfolio delete <name>",
       "portfolio add <portfolio> <symbols...> [--file <path>]",
       "portfolio remove <portfolio> <symbols...> [--file <path>]",
-      "portfolio position set <portfolio> <symbol> <shares|contracts> <avg-cost> [currency]",
+      "portfolio position set <portfolio> <symbol> <shares|contracts> <avg-cost> [currency] [--date <purchase date> | --cost-fx <rate>]",
       "portfolio cash set <portfolio> <amount> [currency]",
       "portfolio cash clear <portfolio>",
       "portfolio target set <portfolio> <symbol|CASH> <weight%>",
@@ -831,6 +971,8 @@ export const portfolioCliCommand: CliCommandDef = {
       { flags: "--name <portfolio>", description: "portfolio import: the portfolio to create or fill (default: the manager's name and 13F)" },
       { flags: "--notional <amount>", description: "portfolio import: the USD total the shares add up to at the filing's prices (default 100,000)" },
       { flags: "--replace", description: "portfolio import: replace the positions of an existing portfolio of that name" },
+      { flags: "--date <purchase date>", description: `position set: the day it was bought, as ${DATE_OPTION_EXAMPLES}; a holding in another currency converts its cost at that day's FX close` },
+      { flags: "--cost-fx <rate>", description: "position set: the rate a holding in another currency was bought at, in the portfolio's currency per unit of the holding's (32.15 TRY per USD)" },
       { flags: "--explain", description: "portfolio show: follow the report with what its terms mean (Weight, Target, Drift, Trade); gloomberb catalog glossary lists every term" },
     ],
     examples: [
@@ -841,6 +983,9 @@ export const portfolioCliCommand: CliCommandDef = {
       "portfolio add Research --file holdings.csv --dry-run",
       "portfolio position set Research ASML 10 800 EUR",
       "portfolio position set Hedge GC=F -10 4216.30",
+      "portfolio position set Lira BRK-B 10 20310 TRY",
+      "portfolio position set Lira BRK-B 10 410 USD --date 2024-03-01",
+      "portfolio position set Lira KO 40 62.50 USD --cost-fx 32.15",
       "portfolio cash set Research 25000 USD",
       "portfolio target set Research ASML 12.5%",
       "portfolio target set Research CASH 10",
@@ -889,6 +1034,16 @@ export const portfolioCliCommand: CliCommandDef = {
       ctx.fail(error instanceof Error ? error.message : String(error), dripUsage);
     }
     const basis = close ? "regular-close" as const : "latest-print" as const;
+    // A position's purchase date and the rate its cost was bought at, read before anything is looked up.
+    const hasDate = args.some((arg) => arg === "--date" || arg.startsWith("--date="));
+    const dateText = hasDate ? takeOption(args, "--date") ?? "" : undefined;
+    const hasCostFx = args.some((arg) => arg === "--cost-fx" || arg.startsWith("--cost-fx="));
+    const costFxText = hasCostFx ? takeOption(args, "--cost-fx") ?? "" : undefined;
+    if ((hasDate || hasCostFx) && action !== "position") {
+      ctx.fail(`${hasDate ? "--date" : "--cost-fx"} is an option of portfolio position set, not portfolio ${action ?? "list"}.`, POSITION_USAGE);
+    }
+    const purchaseDate = dateText != null ? parsePurchaseDate(dateText, ctx) : undefined;
+    const costFx = costFxText != null ? parseCostFx(costFxText, ctx) : undefined;
     const hasFile = args.some((arg) => arg === "--file" || arg.startsWith("--file="));
     const file = hasFile ? takeOption(args, "--file") ?? "" : undefined;
     if (file != null && action !== "add" && action !== "remove") ctx.fail(`--file is an option of portfolio add and remove, not portfolio ${action ?? "list"}.`, ADD_USAGE);
@@ -936,15 +1091,11 @@ export const portfolioCliCommand: CliCommandDef = {
 
     if (action === "position") {
       const subaction = args[1];
-      if (subaction !== "set") {
-        ctx.fail("Usage: gloomberb portfolio position set <portfolio> <ticker> <shares|contracts> <avg-cost> [currency]");
-      }
+      if (subaction !== "set") ctx.fail(POSITION_USAGE);
       const [, , ...rest] = args;
       const currency = rest[4];
-      if (rest.length < 4) {
-        ctx.fail("Usage: gloomberb portfolio position set <portfolio> <ticker> <shares|contracts> <avg-cost> [currency]");
-      }
-      await setPositionCommand(rest[0]!, rest[1]!, rest[2]!, rest[3]!, currency, exchange, ctx);
+      if (rest.length < 4) ctx.fail(POSITION_USAGE);
+      await setPositionCommand(rest[0]!, rest[1]!, rest[2]!, rest[3]!, currency, exchange, ctx, { date: purchaseDate, costFx });
       return;
     }