@datarails-ai/dr-cli 1.6.97 → 1.6.99

package/README.md

@@ -230,6 +230,20 @@ under one identity and run as another.
 { "apiKey": "<key>", "server": "DEV", "email": "svc@datarails.com" }
 ```
 
+The key may instead live in an environment variable, with the file carrying
+only the variable's **name** — the shape for CI (the key stays in the runner's
+secret env, never on disk) and for agent sandboxes (where the variable's
+in-sandbox value is an opaque vault placeholder substituted at egress, passed
+verbatim and never validated):
+
+```json
+{ "apiKeyEnvVar": "DR_API_KEY", "server": "DEV", "email": "svc@datarails.com" }
+```
+
+`apiKey` and `apiKeyEnvVar` are mutually exclusive — a file carrying both is
+refused rather than guessed about. An unset variable fails the command with an
+error naming it; the stored file is never modified by that failure.
+
 `email` names the stored identity — what `--account` selects and what the
 keychain entry is keyed by. It need not match the principal the key is bound to;
 the token the exchange mints is what every request authenticates as, and
@@ -463,6 +477,60 @@ plugins tree (manifests, frontmatter, versions, the facts file, `CONTRIBUTING.md
 `node --test plugins/dr-cli/hooks/tests/auto-update.test.js` runs the hook's
 contract suite.
 
+### The endpoint inventory
+
+`scopes-endpoints.snapshot.json` lists, for every leaf command, the HTTP endpoints it
+can reach — a top-level, non-empty JSON array of
+`{command, method, url_template, service, certainty, non_integer_params?}` records.
+It is the input of the scope contract gate in dr-datarails-server
+(`HippiWeb/JWT_auth/scope_contract.py`). Today that gate checks that each record's URL
+resolves to a monolith view and that the view declares its scope; holding a command's
+endpoints against its ceiling in `scopes-map.snapshot.json` is what DR-53487 may add.
+`pnpm gen:endpoints` also writes the same bytes to `dist/scopes-endpoints.json`.
+
+- **Superset rule.** The list may hold an endpoint a command never actually sends, but
+  never omits one it can send: a gate built on it may over-report, never under-report.
+- **`certainty`.** `static` was read from the call and linked to the leaf through the
+  call graph; `inferred` is a curated or fallback attribution.
+- **`url_template`.** A path only, no host and no query; a dynamic segment is `{name}`.
+- **`non_integer_params`.** The placeholders whose value is not a number (uuid, token,
+  slug…), so substituting a literal `1` will not resolve that route. Absent means every
+  placeholder takes an integer.
+- **`service`.** Which service serves the path: `monolith`, `finance-os`,
+  `spend-control`, `multi-product`, `desk`, `connectors`, `onboarding-validation`.
+  A consumer checking one service filters on it.
+- **`command: "*"`.** A call any authenticated command may trigger (JWT mint/refresh,
+  API-key and login-as re-exchange).
+- **Leaves with no record** are explained in `scripts/scopes-map.sources.json` under
+  `endpoints`: `noHttpCommands` (no Datarails call) and `externalCommands` (the App Space
+  leaves mounted from `@datarails-ai/dr-appspace-cli`, which owns its own contract).
+
+```
+pnpm gen:endpoints        # rewrite the snapshot (and dist/scopes-endpoints.json)
+pnpm check:endpoints      # what CI runs: exit 1 on drift
+```
+
+The generator is static analysis plus the curated tables in `scopes-map.sources.json`;
+its header (`scripts/gen-endpoints.mts`) documents each step and every fatal case.
+`scripts/gen-endpoints.spotcheck.test.mts` runs a few leaves under msw and checks the
+requests they send are in the snapshot — a sample, not the mechanism. Adding a command
+or an api call changes the snapshot: run `pnpm gen:endpoints` and commit the diff.
+
+**Transferring it to dr-datarails-server.** The snapshot is copied by hand, with the
+dr-cli version it was taken at (the `version` in `package.json` at that commit), assuming
+both repos are checked out side by side:
+
+```bash
+cp dr-cli/scopes-endpoints.snapshot.json dr-datarails-server/HippiWeb/JWT_auth/tests/fixtures/dr_cli_endpoints.json
+node -p "require('./dr-cli/package.json').version" > dr-datarails-server/HippiWeb/JWT_auth/tests/fixtures/dr_cli_endpoints.version
+```
+
+A missing fixture makes the server test skip with a reason; a broken one is a hard
+failure. Lifting the skip is DR-53487. Two caveats for that work: the server's
+`contract_violations` currently resolves every record against the monolith URLconf and
+does not filter by `service`, so it must filter to `service == "monolith"`, and it must
+decide how to treat `command: "*"` records and `non_integer_params`.
+
 ### Adding a gated (destructive/sensitive) command
 
 Sensitive writes route through `twoStepConfirm` (`src/commands/_confirm.ts`),

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.97",
+  version: "1.6.99",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -29,6 +29,8 @@ var package_default = {
     build: "tsup",
     "gen:scopes": "tsx scripts/gen-scopes-map.mts",
     "check:scopes": "tsx scripts/gen-scopes-map.mts --check",
+    "gen:endpoints": "tsx scripts/gen-endpoints.mts",
+    "check:endpoints": "tsx scripts/gen-endpoints.mts --check",
     typecheck: "tsc -p tsconfig.build.json --noEmit",
     test: "vitest run",
     "test:watch": "vitest",
@@ -38,7 +40,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -67,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-05T07:44:13.912Z";
+var BUILD_TIME = "2026-10-05T12:03:05.855Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -151,14 +153,17 @@ function parseApiKeyExpiry(value) {
 function hasApiKey(s) {
   return s.apiKey !== void 0 && s.apiKey !== "";
 }
+function hasApiKeyEnvVar(s) {
+  return s.apiKeyEnvVar !== void 0 && s.apiKeyEnvVar !== "";
+}
 function isImpersonatedSession(s) {
   return s.impersonatorEmail !== void 0 && s.impersonatorEmail !== "";
 }
 function isCookielessSession(s) {
-  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s);
+  return isImpersonatedSession(s) || s.cookieless === true || hasApiKey(s) || hasApiKeyEnvVar(s);
 }
 function usesApiKey(s) {
-  return hasApiKey(s) && !isImpersonatedSession(s);
+  return (hasApiKey(s) || hasApiKeyEnvVar(s)) && !isImpersonatedSession(s);
 }
 var KeychainError = class extends Error {
   constructor(message, options) {
@@ -294,6 +299,16 @@ var credentialsFileSchema = z.object({
   // A user-bound API key, exchanged for `access` on demand. A file may hold
   // only this; `access` then appears after the first exchange.
   apiKey: z.string().min(1).optional(),
+  // DR-52657: the NAME of an environment variable holding the API key, for
+  // provisioners that must not put the key on disk — an agent sandbox, where
+  // the variable's in-sandbox value is an opaque vault placeholder
+  // substituted at egress, or a CI runner keeping the key in its secret env.
+  // The value is resolved at exchange time and passed verbatim; dr-cli never
+  // inspects, validates, or logs it. Mutually exclusive with `apiKey` (a
+  // refinement below): a file carrying both is ambiguous about which
+  // credential authenticates it, and silently preferring either one turns a
+  // provisioning mistake into commands running as the wrong key.
+  apiKeyEnvVar: z.string().min(1).optional(),
   // Carried verbatim, judged by `parseApiKeyExpiry` where it is read. Not
   // validated here, and not `.catch(undefined)` either: a rotation rewrites
   // the whole file from the parsed object, so a value this schema dropped
@@ -332,13 +347,19 @@ var credentialsFileSchema = z.object({
 }).passthrough().refine((c) => c.sessionId === void 0 === (c.csrfToken === void 0), {
   message: "sessionId and csrfToken must be provided together",
   path: ["sessionId"]
-}).refine((c) => c.access !== void 0 || c.apiKey !== void 0, {
-  message: "one of access or apiKey is required",
+}).refine((c) => !(c.apiKey !== void 0 && c.apiKeyEnvVar !== void 0), {
+  message: "apiKey and apiKeyEnvVar are mutually exclusive",
+  path: ["apiKeyEnvVar"]
+}).refine((c) => c.access !== void 0 || c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0, {
+  message: "one of access, apiKey or apiKeyEnvVar is required",
   path: ["access"]
-}).refine((c) => c.apiKey !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0, {
-  message: "refresh is required unless an apiKey or a session cookie is present",
-  path: ["refresh"]
-});
+}).refine(
+  (c) => c.apiKey !== void 0 || c.apiKeyEnvVar !== void 0 || c.refresh !== void 0 || c.sessionId !== void 0,
+  {
+    message: "refresh is required unless an apiKey, apiKeyEnvVar or a session cookie is present",
+    path: ["refresh"]
+  }
+);
 function credentialsFilePath() {
   const override = process.env[CREDENTIALS_FILE_ENV];
   return override !== void 0 && override !== "" ? override : DEFAULT_CREDENTIALS_FILE;
@@ -801,7 +822,13 @@ async function exchangeApiKey(host, apiKey, options) {
   if (key === "") {
     throw new Error("api-key exchange: the stored API key is empty");
   }
-  if (!/^[\x21-\x7e]+$/.test(key)) {
+  if (options?.opaque === true) {
+    if (/[\r\n\0]/.test(key) || !/^[\x00-\xff]+$/.test(key)) {
+      throw new Error(
+        "api-key exchange: the environment variable named by apiKeyEnvVar holds a value that cannot travel in an HTTP header (a line break, NUL, or a character above U+00FF)"
+      );
+    }
+  } else if (!/^[\x21-\x7e]+$/.test(key)) {
     throw new Error(
       "api-key exchange: dr only accepts an API key of printable ASCII with no spaces; the stored one contains whitespace, control characters, or non-ASCII characters"
     );
@@ -965,10 +992,31 @@ function mintedByApiKey(token) {
 function apiKeyFingerprint(apiKey) {
   return createHash("sha256").update(apiKey.trim()).digest("hex").slice(0, 32);
 }
+function resolveApiKeyMaterial(session) {
+  if (session.apiKey !== void 0 && session.apiKey !== "") {
+    return { key: session.apiKey, fromEnv: false };
+  }
+  const name = session.apiKeyEnvVar;
+  if (name === void 0 || name === "") {
+    throw new Error("api-key exchange: the session carries no API key");
+  }
+  const value = process.env[name];
+  if (value === void 0 || value === "") {
+    throw new Error(
+      `api-key exchange: the credential file names environment variable ${name} as the API-key carrier, but it is unset or empty in this environment`
+    );
+  }
+  return { key: value, fromEnv: true };
+}
 function mintedByStoredApiKey(session) {
   if (!mintedByApiKey(session.jwtAccess)) return false;
-  if (session.apiKey === void 0 || session.apiKey === "") return false;
-  return session.jwtApiKeyFingerprint === apiKeyFingerprint(session.apiKey);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch {
+    return false;
+  }
+  return session.jwtApiKeyFingerprint === apiKeyFingerprint(material.key);
 }
 function apiKeyStaleBuffer(session, identity2, fallbackMs) {
   if (session.jwtAccess === void 0 || session.jwtAccess === "") return fallbackMs;
@@ -995,12 +1043,13 @@ function ttlOf(token) {
 function exchangeForSession(store, serverKey, email, session, host, opts) {
   const identity2 = `${serverKey}:${email}`;
   if (opts.signal?.aborted === true) return Promise.reject(opts.signal.reason);
-  const key = JSON.stringify([
-    identity2,
-    host,
-    opts.force,
-    apiKeyFingerprint(session.apiKey)
-  ]);
+  let material;
+  try {
+    material = resolveApiKeyMaterial(session);
+  } catch (err) {
+    throw new SessionExpiredError(`${identity2} (${msgOf3(err)})`);
+  }
+  const key = JSON.stringify([identity2, host, opts.force, apiKeyFingerprint(material.key)]);
   const pending = inFlightExchanges.get(key);
   if (pending !== void 0) return joinExchange(pending, opts.signal);
   const controller = new AbortController();
@@ -1015,7 +1064,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
     for (; ; ) {
       let tok;
       try {
-        tok = await exchangeApiKey(host, session.apiKey, { signal });
+        tok = await exchangeApiKey(host, material.key, { signal, opaque: material.fromEnv });
       } catch (err) {
         const cachedIsUsable = !opts.force && mintedByStoredApiKey(session) && !jwtExpiringSoon(session, 0);
         if (!(err instanceof ApiKeyExchangeError)) {
@@ -1054,7 +1103,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
         // the token did not come from. Read back by `mintedByStoredApiKey` on
         // every later command to tell this token apart from one the previous
         // key minted.
-        jwtApiKeyFingerprint: apiKeyFingerprint(session.apiKey),
+        jwtApiKeyFingerprint: apiKeyFingerprint(material.key),
         // Dropped, not carried: the exchange mints no refresh token, and the
         // refresh rung is closed to a keyed identity by contract. Clearing it
         // is what lets "keyed, and still holding a refresh token" mean "these
@@ -1065,7 +1114,7 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
       };
       try {
         const current = await store.getSession(serverKey, email);
-        if (current === void 0 || current.apiKey !== session.apiKey) {
+        if (current === void 0 || current.apiKey !== session.apiKey || current.apiKeyEnvVar !== session.apiKeyEnvVar) {
           return next;
         }
         await store.saveSession(serverKey, next);
@@ -1383,7 +1432,8 @@ var KeyringStore = class _KeyringStore {
     const impersonated = impersonatorEmail !== "";
     const cookielessFlag = parsed2.cookieless === true;
     const apiKey = await this.backend.get(SERVICE, `${sessionAccount}:apikey`);
-    const keyPresent = apiKey !== void 0 && apiKey !== "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
+    const keyPresent = apiKey !== void 0 && apiKey !== "" || apiKeyEnvVar !== "";
     const cookieless = impersonated || cookielessFlag || keyPresent;
     const halfCookie = sessionId === "" !== (csrfToken === "");
     if (savedAtStr === "" || halfCookie || !cookieless && sessionId === "") {
@@ -1429,9 +1479,12 @@ var KeyringStore = class _KeyringStore {
     if (jwtRefresh !== void 0 && jwtRefresh !== "") {
       session.jwtRefresh = jwtRefresh;
     }
-    if (keyPresent) {
+    if (apiKey !== void 0 && apiKey !== "") {
       session.apiKey = apiKey;
     }
+    if (apiKeyEnvVar !== "") {
+      session.apiKeyEnvVar = apiKeyEnvVar;
+    }
     return session;
   }
   /**
@@ -1463,9 +1516,9 @@ var KeyringStore = class _KeyringStore {
     const impersonated = isImpersonatedSession(session);
     if (isCookielessSession(session)) {
       const hasJwt = session.jwtAccess !== void 0 && session.jwtAccess !== "";
-      if (!hasJwt && !hasApiKey(session)) {
+      if (!hasJwt && !hasApiKey(session) && !hasApiKeyEnvVar(session)) {
         throw new Error(
-          "saveSession: cookie-less session must have a jwtAccess token or an apiKey"
+          "saveSession: cookie-less session must have a jwtAccess token, an apiKey, or an apiKeyEnvVar"
         );
       }
       if (session.sessionId === "" !== (session.csrfToken === "")) {
@@ -1496,6 +1549,9 @@ var KeyringStore = class _KeyringStore {
     if (session.jwtApiKeyFingerprint !== void 0 && session.jwtApiKeyFingerprint !== "") {
       metaBlob.jwtApiKeyFingerprint = session.jwtApiKeyFingerprint;
     }
+    if (hasApiKeyEnvVar(session)) {
+      metaBlob.apiKeyEnvVar = session.apiKeyEnvVar;
+    }
     if (impersonated) {
       metaBlob.impersonatorEmail = session.impersonatorEmail;
       if (session.impersonatedUserId !== void 0) {
@@ -2599,7 +2655,9 @@ var FileKeyringBackend = class _FileKeyringBackend {
       // Named as the Session field, since the blob is what `getSession` reads.
       ...creds.accessApiKeyFingerprint !== void 0 && {
         jwtApiKeyFingerprint: creds.accessApiKeyFingerprint
-      }
+      },
+      // The env var's NAME only — the resolved key never enters any store.
+      ...creds.apiKeyEnvVar !== void 0 && { apiKeyEnvVar: creds.apiKeyEnvVar }
     });
   }
   static slotOf(creds, account) {
@@ -2627,11 +2685,16 @@ var FileKeyringBackend = class _FileKeyringBackend {
     const csrfToken = typeof parsed2.csrfToken === "string" ? parsed2.csrfToken : "";
     const apiKeyExpiresAt = typeof parsed2.apiKeyExpiresAt === "string" ? parsed2.apiKeyExpiresAt : "";
     const accessApiKeyFingerprint = typeof parsed2.jwtApiKeyFingerprint === "string" ? parsed2.jwtApiKeyFingerprint : "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" ? parsed2.apiKeyEnvVar : "";
     return {
       ...sessionId !== "" && { sessionId },
       ...csrfToken !== "" && { csrfToken },
       ...apiKeyExpiresAt !== "" && { apiKeyExpiresAt },
-      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint }
+      ...accessApiKeyFingerprint !== "" && { accessApiKeyFingerprint },
+      // Set-if-present, never deleted on a blob that lost it (the
+      // `apiKeyExpiresAt` rule): it is the identity's only credential pointer,
+      // and a meta rewrite must not be able to brick the file.
+      ...apiKeyEnvVar !== "" && { apiKeyEnvVar }
     };
   }
   async get(_service, account) {
@@ -2724,6 +2787,7 @@ var FileKeyringBackend = class _FileKeyringBackend {
             if (meta.apiKeyExpiresAt !== void 0) next.apiKeyExpiresAt = meta.apiKeyExpiresAt;
             if (meta.accessApiKeyFingerprint === void 0) delete next.accessApiKeyFingerprint;
             else next.accessApiKeyFingerprint = meta.accessApiKeyFingerprint;
+            if (meta.apiKeyEnvVar !== void 0) next.apiKeyEnvVar = meta.apiKeyEnvVar;
             break;
           }
         }
@@ -25516,6 +25580,62 @@ function symbolForCurrencyCode(code) {
   return FX_CURRENCY_SYMBOLS.get(code.trim().toUpperCase()) ?? null;
 }
 
+// src/commands/_currencySymbol.ts
+var FIXED_SIGNS_RE = /"[$€£₪]"|[$€£₪]/g;
+var DEFAULT_NUMBER_FORMAT = "#,###";
+function stripFixedCurrencySigns(format) {
+  return format ? format.replace(FIXED_SIGNS_RE, "") : format;
+}
+function withCurrencySign(format, sign) {
+  const cleanSign = sign.replace(/"/g, "");
+  const literal = `"${cleanSign}${/^[A-Za-z]+$/.test(cleanSign) ? " " : ""}"`;
+  const base = format || DEFAULT_NUMBER_FORMAT;
+  return base.split(";").map((section) => {
+    if (section === "") return section;
+    const leading = section.match(/^(\[[^\]]*\])*(?=.)/)?.[0] ?? "";
+    const rest = section.slice(leading.length);
+    const paren = rest.match(/^\((.*)\)$/);
+    return paren ? `${leading}(${literal}${paren[1]})` : `${leading}${literal}${rest}`;
+  }).join(";");
+}
+function parseWidgetOptions(raw) {
+  if (raw === void 0 || raw === null || raw === "") return {};
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed2 = JSON.parse(raw);
+    return typeof parsed2 === "object" && parsed2 !== null && !Array.isArray(parsed2) ? parsed2 : null;
+  } catch {
+    return null;
+  }
+}
+function readAutoCurrencySymbol(raw) {
+  const opts = parseWidgetOptions(raw);
+  if (opts === null) return null;
+  return opts["autoCurrencySymbol"] === true;
+}
+function setAutoCurrencySymbol(raw, enabled) {
+  const opts = parseWidgetOptions(raw);
+  if (opts === null) {
+    throw new Error("widget options is not a JSON object \u2014 refusing to rewrite it");
+  }
+  return JSON.stringify({ ...opts, autoCurrencySymbol: enabled });
+}
+function fixedSignOf(format) {
+  if (typeof format !== "string") return null;
+  const m = format.match(/^(?:\[[^\]]*\])*\(?"([^"]+)"/);
+  const sign = m?.[1];
+  return sign === void 0 ? null : sign.trim();
+}
+function describeCurrencySymbol(widget) {
+  const auto = readAutoCurrencySymbol(widget["options"]);
+  if (auto === true && widget["is_fx_aware"] === true) {
+    return "Auto (follows the dashboard FX selector)";
+  }
+  const sign = fixedSignOf(widget["values_format"]);
+  return sign === null ? "none" : `"${sign}" (fixed)`;
+}
+
 // src/commands/fxConfig.ts
 function writeTable20(out, rows) {
   if (rows.length === 0) return;
@@ -26509,6 +26629,11 @@ async function runFxConvertWidgets(cfg) {
       "--force-sum has no meaning with --off (turning conversion off never touches the aggregator)"
     );
   }
+  if (cfg.disable && !cfg.autoSymbol) {
+    throw new Error(
+      "--no-auto-symbol has no meaning with --off (turning conversion off always clears the Auto currency symbol)"
+    );
+  }
   let targetDashboards;
   if (cfg.all) {
     const dashboards = await list8(cfg.client, { signal: cfg.signal });
@@ -26557,6 +26682,7 @@ async function runFxConvertWidgets(cfg) {
       const v0 = vals !== null && vals.length === 1 ? vals[0] : null;
       const val = v0 !== null && typeof v0 === "object" ? v0 : null;
       const aggregator = val !== null ? String(val["aggregator"] ?? "").toUpperCase() : "";
+      const autoSymbol = readAutoCurrencySymbol(raw["options"]);
       if (cfg.disable) {
         plan.push({
           dashboardId: target.id,
@@ -26565,7 +26691,8 @@ async function runFxConvertWidgets(cfg) {
           widgetName,
           aggregator,
           raw,
-          status: isAware ? "revert" : "already-off"
+          status: isAware ? "revert" : "already-off",
+          autoSymbol
         });
         continue;
       }
@@ -26597,12 +26724,25 @@ async function runFxConvertWidgets(cfg) {
         widgetName,
         aggregator,
         raw,
-        status: status2
+        status: status2,
+        autoSymbol
       });
     }
   }
   const subjectOf = (p) => `widget ${p.widgetId} "${p.widgetName}" (dashboard ${p.dashboardId} "${p.dashboardName}")`;
-  const describeEntry = (p) => planLine(p.status, subjectOf(p), p.aggregator);
+  const symbolNote = (p) => {
+    if (p.status === "convert" || p.status === "convert-sum") {
+      return cfg.autoSymbol ? " (+ Auto currency symbol)" : "";
+    }
+    if (p.status === "already" && p.autoSymbol === false) {
+      return ` (fixed currency symbol \u2014 \`dr widgets set-currency-symbol ${p.widgetId} -d ${p.dashboardId} --auto\` to follow the FX selector)`;
+    }
+    if (p.status === "revert" && p.autoSymbol === true) {
+      return " (Auto currency symbol \u2192 none)";
+    }
+    return "";
+  };
+  const describeEntry = (p) => planLine(p.status, subjectOf(p), p.aggregator) + symbolNote(p);
   const targets = plan.filter((p) => isActionable(p.status, cfg.disable));
   const needsRole = plan.filter((p) => p.status === "needs-fx-role").length;
   const summary = () => {
@@ -26618,6 +26758,7 @@ ${needsRole} skipped for a missing fx_role \u2014 ${FX_ROLE_HINT}.` : "");
       writeJSONIndented(cfg.out, {
         dry_run: true,
         direction: cfg.disable ? "off" : "on",
+        auto_symbol: cfg.disable ? false : cfg.autoSymbol,
         scanned,
         not_eligible: notEligible,
         plan: plan.map((p) => ({
@@ -26626,7 +26767,8 @@ ${needsRole} skipped for a missing fx_role \u2014 ${FX_ROLE_HINT}.` : "");
           widget_id: p.widgetId,
           name: p.widgetName,
           aggregator: p.aggregator,
-          status: p.status
+          status: p.status,
+          auto_currency_symbol: p.autoSymbol
         })),
         unreadable
       });
@@ -26666,10 +26808,19 @@ ${needsRole} skipped for a missing fx_role \u2014 ${FX_ROLE_HINT}.` : "");
           const v0 = vals[0];
           body["vals"] = [{ ...v0, aggregator: "SUM" }];
         }
+        let wantAuto = null;
+        if (want && cfg.autoSymbol) wantAuto = true;
+        else if (!want && p.autoSymbol === true) wantAuto = false;
+        if (wantAuto !== null) body["options"] = setAutoCurrencySymbol(p.raw["options"], wantAuto);
         const res = await update6(cfg.client, p.dashboardId, p.widgetId, body, {
           signal: cfg.signal
         });
         assertFxAwareEcho(res["is_fx_aware"], want, "widget");
+        if (wantAuto !== null && readAutoCurrencySymbol(res["options"]) !== wantAuto) {
+          throw new Error(
+            `server did not keep options.autoCurrencySymbol=${wantAuto} (the Auto currency symbol)`
+          );
+        }
         results.push({
           dashboard_id: p.dashboardId,
           widget_id: p.widgetId,
@@ -26678,8 +26829,10 @@ ${needsRole} skipped for a missing fx_role \u2014 ${FX_ROLE_HINT}.` : "");
         });
         if (!cfg.asJson) {
           for (const line of unreadableLines(unreadable, "dashboard")) cfg.out.write(line + "\n");
-          cfg.out.write(`\u2713 ${describeConvertStatus(p.status, subjectOf(p), p.aggregator)}
-`);
+          cfg.out.write(
+            `\u2713 ${describeConvertStatus(p.status, subjectOf(p), p.aggregator)}${symbolNote(p)}
+`
+          );
         }
       } catch (err) {
         if (cfg.signal.aborted) throw err;
@@ -27018,11 +27171,14 @@ function registerFxConfigCommands(fx) {
   addServerFlag(convertFunctionsCmd);
   addAccountFlag(convertFunctionsCmd);
   const convertWidgetsCmd = fx.command("convert-widgets").description(
-    "Enable currency conversion (is_fx_aware=true) on every eligible dashboard widget (PUT /api/dashboards/<d>/widgets/<w>, round-tripping the widget body verbatim). Eligible = the value section holds exactly one field, that field is Monetary, and it carries an fx_role. Widgets whose aggregator is not SUM are skipped unless --force-sum switches them to SUM. The server has the final say on the flag \u2014 a widget it deems ineligible is reported as failed. Use --off to sweep the other way and turn conversion off \u2014 a rollback, which ignores eligibility and the aggregator and acts on the stored flag alone. Dry-run by default \u2014 prints the plan; re-run with --confirm to apply. Scope with --dashboard <id> or sweep --all."
+    "Enable currency conversion (is_fx_aware=true) on every eligible dashboard widget (PUT /api/dashboards/<d>/widgets/<w>, round-tripping the widget body verbatim). Eligible = the value section holds exactly one field, that field is Monetary, and it carries an fx_role. Widgets whose aggregator is not SUM are skipped unless --force-sum switches them to SUM. The server has the final say on the flag \u2014 a widget it deems ineligible is reported as failed. Each converted widget also switches to the Auto currency symbol (options.autoCurrencySymbol=true \u2014 the sign of the currency selected on the dashboard), as the widget editor does; --no-auto-symbol keeps the stored number format instead. Use --off to sweep the other way and turn conversion off \u2014 a rollback, which ignores eligibility and the aggregator and acts on the stored flag alone (and clears Auto, which only renders on a currency-aware widget). Dry-run by default \u2014 prints the plan; re-run with --confirm to apply. Scope with --dashboard <id> or sweep --all."
   ).option("--dashboard <id>", "Convert widgets on this dashboard only").option("--all", "Convert widgets on every dashboard", false).option(
     "--force-sum",
     "Also convert non-SUM widgets by switching their aggregator to SUM",
     false
+  ).option(
+    "--no-auto-symbol",
+    "Keep each converted widget's stored number format (its fixed currency sign, if any) instead of switching it to the Auto currency symbol"
   ).option(
     "--off",
     "Reverse direction: turn currency conversion OFF on every currency-aware widget in scope",
@@ -27038,6 +27194,7 @@ function registerFxConfigCommands(fx) {
           all: opts.all === true,
           forceSum: opts.forceSum === true,
           disable: opts.off === true,
+          autoSymbol: opts.autoSymbol !== false,
           confirm: opts.confirm === true,
           asJson: opts.json === true,
           signal: setup.signal,
@@ -41169,6 +41326,10 @@ async function runWidgetsGet(cfg) {
   cfg.out.write(`chart_type:  ${found["chart_type"] ?? ""}
 `);
   cfg.out.write(`template_id: ${found["template_id"] ?? "(none)"}
+`);
+  cfg.out.write(`fx_aware:    ${found["is_fx_aware"] === true ? "yes" : "no"}
+`);
+  cfg.out.write(`fx_symbol:   ${describeCurrencySymbol(found)}
 `);
   cfg.out.write("\n(use --json for the full widget body)\n");
 }
@@ -41247,6 +41408,67 @@ async function runWidgetsUpdate(cfg) {
   });
   printWidgetMutation(cfg.out, updated, "Updated", cfg.asJson);
 }
+async function runWidgetsSetCurrencySymbol(cfg) {
+  if (cfg.dashboardId <= 0) throw new Error("--dashboard is required");
+  if (cfg.id <= 0) throw new Error("widget id must be positive");
+  const sign = cfg.mode === "sign" ? (cfg.sign ?? "").trim() : "";
+  if (cfg.mode === "sign" && (sign === "" || sign.length > 5 || sign.includes('"'))) {
+    throw new Error(
+      "--sign needs a currency sign of 1\u20135 characters without quotes (e.g. $, \u20AC, \xA3, \u20AA or a code such as CHF)"
+    );
+  }
+  const all = await listRaw3(cfg.client, cfg.dashboardId, { signal: cfg.signal });
+  const found = all.find((w) => w["id"] === cfg.id);
+  if (found === void 0) {
+    throw new Error(`widget ${cfg.id} not found on dashboard ${cfg.dashboardId}`);
+  }
+  if (cfg.mode === "auto" && found["is_fx_aware"] !== true) {
+    throw new Error(
+      `widget ${cfg.id} is not currency-aware \u2014 the Auto symbol only renders on a widget with currency conversion on; run dr fx convert-widgets --dashboard ${cfg.dashboardId} first`
+    );
+  }
+  const wantAuto = cfg.mode === "auto";
+  const current = typeof found["values_format"] === "string" ? found["values_format"] : null;
+  const body = {
+    ...found,
+    options: setAutoCurrencySymbol(found["options"], wantAuto)
+  };
+  if (cfg.mode === "none") {
+    body["values_format"] = stripFixedCurrencySigns(current) || null;
+  } else if (cfg.mode === "sign") {
+    body["values_format"] = withCurrencySign(stripFixedCurrencySigns(current), sign);
+  }
+  const res = await update6(cfg.client, cfg.dashboardId, cfg.id, body, {
+    signal: cfg.signal
+  });
+  if (readAutoCurrencySymbol(res["options"]) !== wantAuto) {
+    throw new Error(
+      `server did not keep options.autoCurrencySymbol=${wantAuto} (the Auto currency symbol)`
+    );
+  }
+  if (cfg.mode !== "auto" && (res["values_format"] ?? null) !== body["values_format"]) {
+    throw new Error(
+      `server did not keep values_format ${JSON.stringify(body["values_format"])} (came back ${JSON.stringify(res["values_format"] ?? null)})`
+    );
+  }
+  if (cfg.asJson) {
+    writeJSONIndented(cfg.out, {
+      id: res["id"] ?? cfg.id,
+      name: res["name"] ?? found["name"] ?? null,
+      is_fx_aware: res["is_fx_aware"] === true,
+      auto_currency_symbol: wantAuto,
+      values_format: res["values_format"] ?? null,
+      currency_symbol: describeCurrencySymbol(res)
+    });
+    return;
+  }
+  cfg.out.write(
+    `widget ${cfg.id} "${String(found["name"] ?? "")}": currency symbol \u2192 ${describeCurrencySymbol(res)}
+`
+  );
+  cfg.out.write(`values_format: ${res["values_format"] ?? "(none)"}
+`);
+}
 async function runWidgetsDelete(cfg) {
   if (cfg.dashboardId <= 0) throw new Error("--dashboard is required");
   if (cfg.id <= 0) throw new Error("widget id must be positive");
@@ -41598,6 +41820,36 @@ function registerWidgetsCommand(root) {
   });
   addServerFlag(updateCmd);
   addAccountFlag(updateCmd);
+  const symbolCmd = widgets.command("set-currency-symbol").description(
+    "Set a widget's currency symbol the way the widget editor's symbol dropdown does. --auto follows the dashboard FX selector (options.autoCurrencySymbol=true; offered on currency-aware widgets only \u2014 see fx convert-widgets); --none shows no sign (clears Auto and strips the fixed $ \u20AC \xA3 \u20AA from the number format); --sign <S> pins one fixed sign as the format's leading literal (clears Auto). Read-modify-write of the widget body (PUT /api/dashboards/<d>/widgets/<w>); the echo is verified."
+  ).argument("<id>", "widget id (positive integer)").requiredOption("-d, --dashboard <id>", "dashboard id (positive integer)").option("--auto", "Follow the dashboard FX selector (currency-aware widgets only)", false).option("--none", "No currency sign", false).option("--sign <S>", "One fixed sign: $ \u20AC \xA3 \u20AA, or a code such as CHF").option("--json", "Output a structured JSON result instead of a summary", false).action(
+    async (idStr, opts) => {
+      const id = parseWidgetIdArg(idStr);
+      const dashboardId = parseDashboardFlag(opts.dashboard);
+      const picked = [opts.auto === true, opts.none === true, opts.sign !== void 0].filter(
+        Boolean
+      ).length;
+      if (picked !== 1) throw new Error("pass exactly one of --auto, --none or --sign <S>");
+      const mode = opts.auto === true ? "auto" : opts.none === true ? "none" : "sign";
+      const setup = await setupCall(opts.server, opts.account);
+      try {
+        await runWidgetsSetCurrencySymbol({
+          client: setup.client,
+          dashboardId,
+          id,
+          mode,
+          sign: opts.sign,
+          asJson: opts.json === true,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(symbolCmd);
+  addAccountFlag(symbolCmd);
   const deleteCmd = widgets.command("delete").description("Delete a widget (two-step confirm)").argument("<id>", "widget id (positive integer)").requiredOption("-d, --dashboard <id>", "dashboard id (positive integer)").option("--confirm-token <tok>", "Token from a prior plan run \u2014 required to actually delete").action(async (idStr, opts) => {
     const id = parseWidgetIdArg(idStr);
     const dashboardId = parseDashboardFlag(opts.dashboard);
@@ -44947,7 +45199,7 @@ import * as nodePath2 from "path";
 var API_PREFIX = "/api/v1";
 var OPERATOR_EMAIL_HEADER = "X-Operator-Email";
 function withOperatorAttribution(client, options) {
-  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
+  const operatorEmail = isImpersonatedSession(client.session) ? client.session.impersonatorEmail : client.session.cookieless === true && !hasApiKey(client.session) && !hasApiKeyEnvVar(client.session) && client.session.interactiveLogin !== true ? void 0 : client.email;
   if (operatorEmail === void 0) return options ?? {};
   return {
     ...options,

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.97",
+  "cliVersion": "1.6.99",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {
@@ -2251,6 +2251,14 @@
         }
       ]
     },
+    "widgets set-currency-symbol": {
+      "requires": [
+        {
+          "resource": "dashboards",
+          "action": "write"
+        }
+      ]
+    },
     "widgets delete": {
       "requires": [
         {

package/dist/skills/dr-cli/SKILL.md

@@ -248,7 +248,10 @@ area's gotchas.
 - `dashboards push <id> --to <orgs> [--override]` — copy a dashboard into other
   organizations (two-step confirm). Destinations must come from
   `organizations push-targets`.
-- `widgets list|get|data|create|update|delete|chart|kpi|pie|table|gauge|waterfall|published-item|text` (alias `widget`)
+- `widgets list|get|data|create|update|set-currency-symbol|delete|chart|kpi|pie|table|gauge|waterfall|published-item|text` (alias `widget`)
+  — `widgets set-currency-symbol <id> -d <dash> --auto|--none|--sign <S>` is the
+  widget editor's currency-symbol dropdown: **Auto** (the sign of the currency
+  selected on the dashboard; currency-aware widgets only), none, or one fixed sign.
   — `widgets data` applies the dashboard's saved filter bar + date picker by
   default so results match the product UI; `--no-dashboard-context` computes
   from the widget's own settings only.
@@ -439,7 +442,7 @@ area's gotchas.
 - `devices list|get|logs|request-logs|received-logs|download-logs|commands|command-delete`
 - `features list`, `features groups list|get`, `features orgs list|add|remove`
 - `semantictables list|get|data|distinct` (alias `semtables`), `fx rates`
-- `fx set-posting|set-reporting` (Monetary field FX roles; `--all-tables` sweeps the org), `fx default-currency` (org-wide default, Super Admin), `fx add-currency` (org custom currency, e.g. BUSD), `fx convert-functions|convert-widgets` (bulk currency-aware sweeps, `--off` to roll back)
+- `fx set-posting|set-reporting` (Monetary field FX roles; `--all-tables` sweeps the org), `fx default-currency` (org-wide default, Super Admin), `fx add-currency` (org custom currency, e.g. BUSD), `fx convert-functions|convert-widgets` (bulk currency-aware sweeps, `--off` to roll back; `convert-widgets` also switches each converted widget to the Auto currency symbol unless `--no-auto-symbol`)
 - `kb search|get|categories|sections|articles-in-section|recent|attachments|article-images`
 - `mcp register|unregister|list|serve`, `skill list|print|install|init-project`
 

package/dist/skills/dr-cli/reference/admin.md

@@ -755,11 +755,38 @@ name.
   **and carries an fx_role**. Non-SUM functions are skipped unless `--force-sum`
   switches them. **Dry-run by default** — always run once without `--confirm` and
   read the plan.
-- `fx convert-widgets (--dashboard <id> | --all) [--force-sum] [--off] [--confirm]` —
+- `fx convert-widgets (--dashboard <id> | --all) [--force-sum] [--no-auto-symbol] [--off] [--confirm]` —
   same sweep for dashboard widgets (eligible = exactly one value field, Monetary,
   with an fx_role). The server has the final say per widget; an echo that doesn't
   confirm the flag is reported as a failure, not silently accepted. Dry-run by
-  default.
+  default. Each converted widget is also switched to the **Auto currency symbol**
+  (see below) — the plan line reads `enable currency conversion (+ Auto currency
+  symbol)`; `--no-auto-symbol` keeps the widget's stored number format instead.
+
+**The currency symbol travels with the flag (DR-53702).** The widget editor's number
+format offers three symbol states: a *fixed* sign (`"$"#,###` — the sign is the
+format's leading literal), *none*, and — on currency-aware widgets only — **Auto**,
+which renders the sign of the currency selected in the dashboard's FX selector (its
+ISO code when a custom currency has no symbol). Auto is not in the format string; it is
+`autoCurrencySymbol: true` inside the widget's `options` JSON blob, and the renderer
+applies it only while `is_fx_aware` is true, stripping any fixed `$ € £ ₪` the format
+still carries. The editor switches a widget to Auto when it becomes currency-aware and
+back to none when it stops being so, and the CLI mirrors that:
+
+- `fx convert-widgets` sets Auto on every widget it converts (the format itself is left
+  alone — the renderer ignores its fixed sign while Auto applies). `--off` clears Auto
+  on widgets that had it. An already-aware widget that still shows a fixed sign is
+  **not** changed by the sweep; the plan names it and points at the per-widget command.
+- `widgets set-currency-symbol <id> -d <dashboard> (--auto | --none | --sign <S>)` is
+  the dropdown for one widget: `--auto` (refused on a widget that is not
+  currency-aware — convert it first), `--none` (clears Auto and strips the fixed
+  `$ € £ ₪` from every section of the format), `--sign <S>` (clears Auto and writes `S`
+  as the leading literal of every section, with the renderer's placement rules — after
+  `[Red]`-style tokens, inside parentheses, a trailing space after a letter code such as
+  `CHF`). Read-modify-write of the server's body with the echo verified; `--json` for
+  the resulting state.
+- `widgets get <id> -d <dashboard>` prints `fx_aware:` and `fx_symbol:` (`Auto …`,
+  `none`, or `"$" (fixed)`) so the state is visible without reading the body.
 
 **Eligibility is stricter server-side than in the web app.** `FxEligibilityService`
 requires the value field to be Monetary AND to have an `fx_role`; the serializer

package/dist/skills/dr-cli/reference/dashboards-widgets.md

@@ -51,6 +51,13 @@ notifications. Confirm with `dashboards list --account <destination>`.
   same as scheduled report emails.
 - `widgets create --file` (power mode), `widgets update <id> --file`,
   `widgets delete <id>` (two-step confirm).
+- `widgets set-currency-symbol <id> -d <dashboard> --auto|--none|--sign <S>` — the
+  widget editor's currency-symbol dropdown from the CLI. `--auto` follows the
+  dashboard FX selector (currency-aware widgets only — `fx convert-widgets` first);
+  `--none` clears Auto and strips the fixed `$ € £ ₪` from the number format;
+  `--sign <S>` pins one fixed sign. `widgets get` shows the current state as
+  `fx_symbol:`. Full semantics under **FX configuration** in
+  [admin.md](admin.md).
 - Flag-driven builders:
   - `widgets chart --type column|bar|line|area` + modifiers `--stacked`
     `--percent` `--smooth`.

package/dist/skills/fx-onboard/SKILL.md

@@ -246,6 +246,13 @@ Rules while executing:
 
 - **Never pass `--force-sum` without saying so in the plan.** It changes a widget's
   aggregator to SUM, which changes what the customer sees.
+- **The widget sweep also switches each converted widget to the Auto currency
+  symbol** (the sign of the currency selected on the dashboard), exactly as the widget
+  editor does — the plan line says `(+ Auto currency symbol)`. Say so in the plan. If
+  the customer wants converted widgets to keep their fixed `$`, pass
+  `--no-auto-symbol`. Widgets that were already currency-aware keep their fixed sign;
+  the plan lists them with the `dr widgets set-currency-symbol <id> -d <dash> --auto`
+  command to run per widget if the customer wants them to follow the selector too.
 - **Never use `--allow-custom` or `--allow-unlisted` to get past a validation error.**
   They exist for a code you know is coming, not to silence a refusal.
 - **Re-runs are safe.** Every command is idempotent — an already-configured field
@@ -307,7 +314,9 @@ These stay manual, and omitting them from the report leaves the job half-done:
 
 - **Widgets / functions:** `dr fx convert-widgets --all --off --confirm` and
   `dr fx convert-functions --off --confirm`. Acts on the stored flag alone, so it also
-  clears flags left on entities that no longer qualify.
+  clears flags left on entities that no longer qualify. `--off` also clears the Auto
+  currency symbol on widgets that had it; a widget's fixed sign, if it had one before
+  conversion, is still in its number format and shows again.
 - **A widget body:** `dr widgets update <id> -d <dashboard> --file before-widget-<id>.json`.
 - **Org default:** `dr fx default-currency --none --confirm` (back to posting currency)
   or set the previous code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.97",
+  "version": "1.6.99",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.10.20",
+    "@datarails-ai/dr-appspace-cli": "0.10.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",
@@ -48,6 +48,8 @@
     "build": "tsup",
     "gen:scopes": "tsx scripts/gen-scopes-map.mts",
     "check:scopes": "tsx scripts/gen-scopes-map.mts --check",
+    "gen:endpoints": "tsx scripts/gen-endpoints.mts",
+    "check:endpoints": "tsx scripts/gen-endpoints.mts --check",
     "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",