@datarails-ai/dr-cli 1.6.100 → 1.6.102

package/README.md

@@ -162,19 +162,23 @@ JWT refresh is automatic. Re-run `login` only when the refresh token itself
 dies (days of idle, password change, admin revoke). Never paste the
 session/JWT — treat them like a password.
 
-**Trying the v2 device flow (`DR_OAUTH_FLOW=v2`).** Set `DR_OAUTH_FLOW=v2` for
-`dr login` to use the monolith's `/oauth/v2/` device flow. The consent page lets
-you pick the credential's scope (below) before "Allow", and the login stores a
-cookie-less JWT pair, with no session, refreshed at the external refresh
-endpoint. The page offers the choice only where the org enforces it; elsewhere
-the token is unrestricted, as today. Unset, or `legacy`, keeps the current flow;
-any other value is refused. The server must be running the v2 endpoints
-(DR-53508). Log in again to switch an identity between flows. Not yet
-supported with a credential file (`DR_CREDENTIALS_FILE`): log in through the
-keychain.
+**Device flow and credential scope.** `dr login` uses the monolith's
+`/oauth/v2/` device flow. The consent page lets you pick the credential's scope
+(below) before "Allow", and the login stores a cookie-less JWT pair, with no
+session, refreshed at the external refresh endpoint. The page offers the choice
+only where the org enforces it; elsewhere the token is unrestricted. This works
+with a credential file too (`DR_CREDENTIALS_FILE`), which records the login as
+`"interactiveLogin": true` so that `dr login` and `dr logout` still accept it.
+
+`DR_OAUTH_FLOW=legacy` runs the old `/oauth/device/code/` flow instead, for a
+server that does not serve `/oauth/v2/` yet (a 404 from the v2 code endpoint
+says so). A legacy token carries **no** credential scope, whatever the person
+would have picked, and the login prints a line saying so. `v2` or unset selects
+the default; any other value is refused. Log in again to switch an identity
+between flows.
 
 ```
-DR_OAUTH_FLOW=v2 dr login --server US       # PowerShell: $env:DR_OAUTH_FLOW="v2"; dr login --server US
+DR_OAUTH_FLOW=legacy dr login --server US   # PowerShell: $env:DR_OAUTH_FLOW="legacy"; dr login --server US
 ```
 
 ### Credential scope
@@ -393,6 +397,7 @@ dr skill print <name>     # print an embedded skill's SKILL.md
 | Data models          | `data-models list/get`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Datamappers          | `datamappers list/get/create/update/delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | Dashboards           | `dashboards list/get/create/delete/prepare`, `dashboards set-date-picker <id> --mode <preset> \| --year YYYY \| --quarter YYYY-Qn \| --month YYYY-MM \| --day YYYY-MM-DD`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Folders              | `folders list/create`, `folders reorder --container <root\|id> (--items folder:12,entity:87 \| --move <kind:id> --to-index <n>)`, `folders move <id> --parent <root\|id>` (dashboard / story picker tree, flag-gated; reorder and move are two-step confirm; a dashboard moves with `dashboards set-folder`)                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Functions            | `functions list/get/create/delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Dynamic ranges       | `dynamic-ranges list/get/data/create/delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Lookups (LUTs)       | `lut list/create/update/delete/reorder/unmapped` (alias `lookups`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

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.100",
+  version: "1.6.102",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -40,7 +40,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.10.21",
+    "@datarails-ai/dr-appspace-cli": "0.10.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-05T12:55:55.787Z";
+var BUILD_TIME = "2026-10-07T11:02:43.513Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -336,6 +336,13 @@ var credentialsFileSchema = z.object({
   // would rewrite live token material after every successful command.
   sessionId: z.string().min(1).optional(),
   csrfToken: z.string().min(1).optional(),
+  // DR-53844: set by a v2 `dr login`, whose pair comes with no cookie, so the
+  // file still reads as a person's login — `dr login` may replace it and
+  // `dr logout` may remove it — rather than as one provisioned externally.
+  // Written by the CLI only. `z.boolean()`, not `z.literal(true)`: a
+  // top-level rejection fails the whole file (see `apiKeyExpiresAt`), and a
+  // hand-edited `false` must read as absent, not lock the operator out.
+  interactiveLogin: z.boolean().optional(),
   // Validated, not just typed: `KeyringStore` turns this straight into a Date
   // and later calls `toISOString()` on it, which throws on an Invalid Date.
   // `datetime()` rejects a bad calendar date (2026-02-30, 2026-13-40) on its
@@ -567,11 +574,18 @@ var UnknownAccountError = class extends Error {
 var SCOPE_DENIED_CODE = 40301;
 var SCOPE_UNDECLARED_CODE = 40302;
 var ScopeDeniedError = class extends Error {
-  constructor(method, path11, code, required2) {
+  /**
+   * @param identity The identity whose ceiling refused, when it is NOT necessarily the one
+   *   the command line selected — `dr login-as --as <operator>` mints with the operator's
+   *   credential, not the `--server`/`--account` one. Named, the message points `dr whoami`
+   *   at it; omitted, "this identity" is the one the reader just ran the command as.
+   */
+  constructor(method, path11, code, required2, identity2) {
     super("");
     this.method = method;
     this.path = path11;
     this.code = code;
+    this.identity = identity2;
     this.name = "ScopeDeniedError";
     this.required = required2;
     this.message = this.render();
@@ -579,6 +593,7 @@ var ScopeDeniedError = class extends Error {
   method;
   path;
   code;
+  identity;
   /** `resource:action` the command needs, joined when it needs more than one. Filled in by
    *  `cli.ts` after construction (see the class docstring); `undefined` until then, and for
    *  a command the local map says nothing about. */
@@ -597,6 +612,10 @@ var ScopeDeniedError = class extends Error {
       return `${this.method} ${this.path}: this endpoint is not yet scope-declared on the server; report to #dr-cli`;
     }
     const needs = this.required === void 0 || this.required === "" ? "" : ` (needs ${this.required})`;
+    if (this.identity !== void 0) {
+      const { server, account } = this.identity;
+      return `${this.method} ${this.path}: the credential scope of ${account} on ${server} does not allow it${needs}; run 'dr whoami --server ${server} --account ${account}' to see the scopes it carries`;
+    }
     return `${this.method} ${this.path}: this identity's credential scope does not allow it${needs}; run 'dr whoami' to see the scopes this identity carries`;
   }
 };
@@ -2657,7 +2676,8 @@ var FileKeyringBackend = class _FileKeyringBackend {
         jwtApiKeyFingerprint: creds.accessApiKeyFingerprint
       },
       // The env var's NAME only — the resolved key never enters any store.
-      ...creds.apiKeyEnvVar !== void 0 && { apiKeyEnvVar: creds.apiKeyEnvVar }
+      ...creds.apiKeyEnvVar !== void 0 && { apiKeyEnvVar: creds.apiKeyEnvVar },
+      ...creds.interactiveLogin === true && { interactiveLogin: true }
     });
   }
   static slotOf(creds, account) {
@@ -2694,7 +2714,8 @@ var FileKeyringBackend = class _FileKeyringBackend {
       // 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 }
+      ...apiKeyEnvVar !== "" && { apiKeyEnvVar },
+      ...parsed2.interactiveLogin === true && { interactiveLogin: true }
     };
   }
   async get(_service, account) {
@@ -2788,6 +2809,8 @@ var FileKeyringBackend = class _FileKeyringBackend {
             if (meta.accessApiKeyFingerprint === void 0) delete next.accessApiKeyFingerprint;
             else next.accessApiKeyFingerprint = meta.accessApiKeyFingerprint;
             if (meta.apiKeyEnvVar !== void 0) next.apiKeyEnvVar = meta.apiKeyEnvVar;
+            if (meta.interactiveLogin === true) next.interactiveLogin = true;
+            else delete next.interactiveLogin;
             break;
           }
         }
@@ -3659,6 +3682,11 @@ var PROD_GATE_TIER_B = /* @__PURE__ */ new Set([
   // cash (dr cash …). rules delete / delete-all / hidden-rules delete → Tier A.
   "cash-rule|update",
   "cash-rules|reorder",
+  // dashboard / story folders (dr folders reorder, dr folders move). Reorder is
+  // per-user (only the caller's own picker order changes) and a move is undone by
+  // another move.
+  "folder-container|reorder",
+  "folder|move",
   "cash-hidden-rules|upsert",
   "cash-ai-rules|trigger",
   // metrics (dr metrics …). delete / dimension|category delete → A.
@@ -4290,9 +4318,17 @@ async function refuseIfProvisionedExternally(action, opts) {
       `cannot ${action}: the credentials in ${path11} are an API key. Run \`dr login --api-key\` to replace the key (and update its \`apiKeyExpiresAt\` in that file, if set \u2014 nothing derives that date, and a stale one warns "expired" on every command), or \`dr logout\` to remove it and log in with a browser instead \u2014 it cannot be read back afterwards, so keep a copy if it is still needed.`
     );
   }
-  if (creds.sessionId !== void 0 && creds.sessionId !== "") return;
+  if (creds.apiKeyEnvVar !== void 0 && opts?.allowApiKey !== true) {
+    throw new Error(
+      `cannot ${action}: the credentials in ${path11} name the environment variable ${creds.apiKeyEnvVar} as their API key, which is what later commands would authenticate as. Remove that file (\`dr logout\`) to log in with a browser instead.`
+    );
+  }
+  if (isInteractiveFileLogin(creds)) return;
   throw provisionedExternallyError(path11, action);
 }
+function isInteractiveFileLogin(creds) {
+  return creds.sessionId !== void 0 && creds.sessionId !== "" || creds.interactiveLogin === true;
+}
 async function refuseLoginOverStoredApiKey(store, serverKey, email) {
   let existing;
   try {
@@ -4323,7 +4359,7 @@ async function refuseImpersonationWithCredentialFile() {
       `cannot ${action}: the credentials in ${path11} are an API key, and an API-key token cannot mint further credentials. Impersonating needs a browser login, so remove that file (\`dr logout\`) and run \`dr login --server <key>\` \u2014 the key cannot be read back afterwards, so keep a copy if it is still needed.`
     );
   }
-  if (creds.sessionId === void 0 || creds.sessionId === "") {
+  if (!isInteractiveFileLogin(creds)) {
     throw provisionedExternallyError(path11, action);
   }
   throw new Error(
@@ -5141,8 +5177,8 @@ var OAUTH_FLOW_ENV = "DR_OAUTH_FLOW";
 function oauthFlowFromEnv(env = process.env) {
   const raw = (env[OAUTH_FLOW_ENV] ?? "").trim();
   const value = raw.toLowerCase();
-  if (value === "" || value === "legacy") return "legacy";
-  if (value === "v2") return "v2";
+  if (value === "" || value === "v2") return "v2";
+  if (value === "legacy") return "legacy";
   throw new Error(`${OAUTH_FLOW_ENV} must be "legacy" or "v2", got "${raw}"`);
 }
 var PATHS = {
@@ -5152,7 +5188,7 @@ var PATHS = {
 var GRANT_TYPE = "urn:ietf:params:oauth:grant-type:";
 async function requestDeviceCode(host, options) {
   const base = host.replace(/\/+$/, "");
-  const flow = options?.flow ?? "legacy";
+  const flow = options?.flow ?? "v2";
   const paths = PATHS[flow];
   const body = new URLSearchParams({ client_id: CLIENT_ID, scope: paths.scope });
   const res = await fetch(`${base}${paths.code}`, {
@@ -5163,7 +5199,12 @@ async function requestDeviceCode(host, options) {
   });
   const text2 = await res.text();
   if (!res.ok) {
-    const hint = flow === "v2" && res.status === 429 ? " (too many logins from this address: wait a minute and run `dr login` again)" : "";
+    let hint = "";
+    if (flow === "v2" && res.status === 429) {
+      hint = " (too many logins from this address: wait a minute and run `dr login` again)";
+    } else if (flow === "v2" && res.status === 404) {
+      hint = ` (this server does not serve the v2 device flow yet: set ${OAUTH_FLOW_ENV}=legacy to log in through the old one, whose token carries no credential scope)`;
+    }
     throw new Error(`device/code failed: ${res.status} ${text2.trim()}${hint}`);
   }
   let raw;
@@ -5530,11 +5571,6 @@ function registerLoginCommand(root) {
     await refuseIfProvisionedExternally("log in");
     const flow = oauthFlowFromEnv();
     const fileStore = await resolveFileStore(opts.server);
-    if (flow === "v2" && fileStore !== void 0) {
-      throw new Error(
-        `DR_OAUTH_FLOW=v2 cannot log into the credential file ${fileStore.path} yet; unset DR_CREDENTIALS_FILE to log in through the keychain, or unset DR_OAUTH_FLOW.`
-      );
-    }
     let serverKey = fileStore?.key ?? (opts.server ?? "").trim();
     if (fileStore === void 0) {
       if (serverKey === "") {
@@ -5643,13 +5679,14 @@ async function runLogin(cfg) {
   await refuseIfProvisionedExternally("log in");
   const host = cfg.host ?? resolve(cfg.serverKey).host;
   const timeoutMs = cfg.timeoutMs !== void 0 && cfg.timeoutMs > 0 ? cfg.timeoutMs : DEFAULT_LOGIN_TIMEOUT_MS;
-  const flow = cfg.flow ?? "legacy";
+  const flow = cfg.flow;
   const controller = new AbortController();
   const overallTimer = setTimeout(() => controller.abort(), timeoutMs + ABORT_SLACK_MS);
   try {
-    if (flow === "v2") {
-      cfg.out.write(`Using the v2 device flow (DR_OAUTH_FLOW=v2).
-`);
+    if (flow === "legacy") {
+      cfg.out.write(
+        "Using the legacy device flow (DR_OAUTH_FLOW=legacy): its token carries no credential scope.\n"
+      );
     }
     const dc = await requestDeviceCode(host, { signal: controller.signal, flow });
     cfg.out.write(`Opening browser to authenticate with Datarails (${cfg.serverKey})...
@@ -6059,7 +6096,17 @@ async function resolveTargetUserId(client, targetEmail, signal) {
     `no user you can log in as matches "${targetEmail}".${near} Use --user-id <n> to impersonate by id.`
   );
 }
-function friendlyLoginAsError(err, targetEmail) {
+var LOGINAS_REQUIRED_SCOPE = "support-manager:write";
+function friendlyLoginAsError(err, targetEmail, explicitOperator) {
+  if (err.code === "insufficient_scope" && err.httpStatus === 403) {
+    return new ScopeDeniedError(
+      "POST",
+      "/jwt/api/loginas/",
+      SCOPE_DENIED_CODE,
+      LOGINAS_REQUIRED_SCOPE,
+      explicitOperator
+    );
+  }
   switch (err.code) {
     case "not_permitted":
       return new Error(`You are not permitted to impersonate ${targetEmail}.`);
@@ -6119,7 +6166,10 @@ async function runLoginAs(cfg) {
       signal: cfg.signal
     });
   } catch (err) {
-    if (err instanceof LoginAsError) throw friendlyLoginAsError(err, cfg.targetEmail);
+    if (err instanceof LoginAsError) {
+      const explicitOperator = cfg.operatorFlag !== void 0 && cfg.operatorFlag !== "" ? { server: cfg.serverKey, account: operatorEmail } : void 0;
+      throw friendlyLoginAsError(err, cfg.targetEmail, explicitOperator);
+    }
     throw err;
   }
   let storageEmail = cfg.targetEmail;
@@ -14346,8 +14396,15 @@ function registerDashboardsCommand(root) {
   addAccountFlag(setFolderCmd);
 }
 
+// src/commands/folders.ts
+import { createHash as createHash3 } from "crypto";
+
 // src/api/folders.ts
 var FOLDER_ENTITY_TYPES = ["dashboard", "story"];
+var FOLDER_FLAGS = {
+  dashboard: "dashboards__folders",
+  story: "storytelling__folders"
+};
 async function list9(client, entityType, options) {
   const out = await client.getJSON(
     `/api/folders/?entity_type=${entityType}`,
@@ -14364,6 +14421,39 @@ async function create4(client, entityType, name, parentId, options) {
   }
   return out;
 }
+async function reorder(client, payload, options) {
+  const path11 = "/api/folders/reorder";
+  const res = await client.do("POST", path11, JSON.stringify(payload), options);
+  if (!res.ok) {
+    throw new Error(`POST ${path11}: HTTP ${res.status}: ${await res.text()}`);
+  }
+}
+async function move(client, folderId, parentId, options) {
+  const path11 = `/api/folders/${folderId}`;
+  const out = await client.patchJSON(path11, { parent_id: parentId }, options);
+  if (out === null) {
+    throw new Error(`unexpected empty response from PATCH ${path11}`);
+  }
+  return out;
+}
+var STORY_PAGE_SIZE = 100;
+async function listEntities(client, entityType, options) {
+  if (entityType === "dashboard") {
+    return await client.getJSON("/api/dashboards/", options) ?? [];
+  }
+  const stories = [];
+  for (let page = 1; ; page++) {
+    const env = await client.getJSON(
+      `/api/storytelling/?page_size=${STORY_PAGE_SIZE}&page=${page}`,
+      options
+    );
+    if (env === null || env.results.length === 0) break;
+    stories.push(...env.results);
+    if (env.next === null) break;
+  }
+  const listed = new Set(stories.map((s) => s.id));
+  return stories.filter((s) => s.parent_story === null || s.is_roll_forwarded || !listed.has(s.parent_story)).map(({ id, name, folder_id, position }) => ({ id, name, folder_id, position }));
+}
 
 // src/commands/folders.ts
 async function runFoldersList(cfg) {
@@ -14373,6 +14463,235 @@ async function runFoldersList(cfg) {
     return;
   }
   renderFolderTree(cfg.out, tree);
+  const entities = await listEntities(cfg.client, cfg.entityType, {
+    signal: cfg.signal
+  });
+  if (tree.length === 0 && entities.length > 0 && entities.every((e) => e.position === null)) {
+    cfg.out.write(
+      `
+folders are disabled for ${cfg.entityType} on this server (Unleash flag ${FOLDER_FLAGS[cfg.entityType]} is off) \u2014 no member order to show.
+`
+    );
+    return;
+  }
+  const names = /* @__PURE__ */ new Map();
+  const walk = (n) => {
+    names.set(n.id, n.name);
+    for (const c of n.children ?? []) walk(c);
+  };
+  for (const root of tree) walk(root);
+  for (const [containerId, members] of buildContainerMembers(tree, entities)) {
+    cfg.out.write(`
+${containerLabel(containerId, names)}:
+`);
+    if (members.length === 0) {
+      cfg.out.write("  (empty)\n");
+      continue;
+    }
+    const rows = members.map((m) => ({
+      cells: [`  ${m.kind}:${m.id}`, m.name, String(m.position ?? "-")]
+    }));
+    writeTable9(cfg.out, rows);
+  }
+}
+function buildContainerMembers(tree, entities) {
+  const out = /* @__PURE__ */ new Map();
+  const add3 = (containerId, children2) => {
+    out.set(
+      containerId,
+      children2.map((f) => ({
+        kind: "folder",
+        id: f.id,
+        name: f.name,
+        position: f.position ?? null
+      }))
+    );
+    for (const f of children2) add3(f.id, f.children ?? []);
+  };
+  add3(null, tree);
+  for (const e of entities) {
+    const bucket = out.get(e.folder_id);
+    if (bucket === void 0) continue;
+    bucket.push({ kind: "entity", id: e.id, name: e.name, position: e.position });
+  }
+  const rank = (m) => m.position ?? Number.MAX_SAFE_INTEGER;
+  for (const members of out.values()) {
+    members.sort(
+      (a, b) => rank(a) - rank(b) || (a.kind === b.kind ? 0 : a.kind === "folder" ? -1 : 1) || a.id - b.id
+    );
+  }
+  return out;
+}
+var ITEM_RE = /^(folder|entity):([1-9][0-9]*)$/;
+function parseReorderItems(raw) {
+  const tokens = raw.split(",").map((t) => t.trim());
+  return tokens.map((t) => {
+    const m = ITEM_RE.exec(t);
+    if (m === null) {
+      throw new Error(`invalid --items entry "${t}" (expected: folder:<id> | entity:<id>)`);
+    }
+    return { kind: m[1], id: Number(m[2]) };
+  });
+}
+function parseContainerOpt(raw, flag) {
+  if (raw === "root") return null;
+  if (!/^[1-9][0-9]*$/.test(raw)) {
+    throw new Error(`invalid ${flag} "${raw}" (expected: root | positive folder id)`);
+  }
+  return Number(raw);
+}
+function moveItem(items, item, toIndex) {
+  const from = items.findIndex((i) => i.kind === item.kind && i.id === item.id);
+  if (from === -1) {
+    throw new Error(`${item.kind}:${item.id} is not in this container`);
+  }
+  const rest = items.filter((_, i) => i !== from).map((i) => ({ kind: i.kind, id: i.id }));
+  rest.splice(Math.min(toIndex, rest.length), 0, { kind: item.kind, id: item.id });
+  return rest;
+}
+function containerLabel(containerId, names) {
+  if (containerId === null) return "root";
+  const name = names.get(containerId);
+  return name === void 0 ? `folder ${containerId}` : `folder ${containerId} (${name})`;
+}
+var itemKey = (i) => `${i.kind}:${i.id}`;
+function reorderConfirmId(entityType, containerArg, request) {
+  const sha = createHash3("sha256").update(request).digest("hex").slice(0, 12);
+  return `${entityType}:${containerArg}:${sha}`;
+}
+function flagOffError(entityType, err) {
+  return new Error(
+    `folders are not enabled for ${entityType} on this server (Unleash flag ${FOLDER_FLAGS[entityType]} is off?): ${err.message}`
+  );
+}
+async function runFoldersReorder(cfg) {
+  const hasItems = cfg.items !== void 0 && cfg.items.trim() !== "";
+  const hasMove = cfg.move !== void 0 && cfg.move.trim() !== "";
+  if (hasItems && hasMove) throw new Error("--items and --move are mutually exclusive");
+  if (!hasItems && !hasMove) throw new Error("one of --items or --move is required");
+  let toIndex = 0;
+  if (hasMove) {
+    if (cfg.toIndex === void 0 || !/^[0-9]+$/.test(cfg.toIndex)) {
+      throw new Error("--move needs --to-index <n> (non-negative integer)");
+    }
+    toIndex = Number(cfg.toIndex);
+  }
+  const given = parseReorderItems(hasItems ? cfg.items ?? "" : cfg.move ?? "");
+  if (hasMove && given.length !== 1) throw new Error("--move takes a single kind:id");
+  const containerArg = cfg.container === null ? "root" : String(cfg.container);
+  const firstGiven = given[0];
+  const request = hasMove && firstGiven !== void 0 ? `move:${itemKey(firstGiven)}@${toIndex}` : given.map(itemKey).join(",");
+  const action = {
+    resource: "folder-container",
+    id: reorderConfirmId(cfg.entityType, containerArg, request),
+    verb: "reorder"
+  };
+  await preflightConfirmToken(action, cfg.token);
+  const opts = { signal: cfg.signal };
+  const [tree, entities] = await Promise.all([
+    list9(cfg.client, cfg.entityType, opts),
+    listEntities(cfg.client, cfg.entityType, opts)
+  ]);
+  const current = buildContainerMembers(tree, entities).get(cfg.container) ?? [];
+  const items = hasMove && firstGiven !== void 0 ? moveItem(current, firstGiven, toIndex) : given;
+  const payload = {
+    entity_type: cfg.entityType,
+    container_id: cfg.container,
+    items
+  };
+  const flags = hasItems ? `--items ${cfg.items?.replace(/\s+/g, "") ?? ""}` : `--move ${cfg.move?.trim() ?? ""} --to-index ${toIndex}`;
+  await twoStepConfirm({
+    out: cfg.out,
+    action,
+    token: cfg.token,
+    server: cfg.serverFlag,
+    confirmCmd: `dr folders reorder --entity-type ${cfg.entityType} --container ${containerArg} ${flags} --server ${cfg.serverFlag}`,
+    describe: async () => {
+      const byKey2 = new Map(current.map((m, i) => [itemKey(m), { m, i }]));
+      const lines = [`container: ${containerArg} (${cfg.entityType})`, "current order:"];
+      if (current.length === 0) lines.push("  (empty)");
+      current.forEach((m, i) => lines.push(`  ${i}  ${itemKey(m)}  ${m.name}`));
+      lines.push("new order:");
+      items.forEach((it, i) => {
+        const was = byKey2.get(itemKey(it));
+        const note = was === void 0 ? "not in container" : was.i === i ? "" : `was ${was.i}`;
+        const name = was?.m.name ?? "?";
+        lines.push(`  ${i}  ${itemKey(it)}  ${name}${note === "" ? "" : `  (${note})`}`);
+      });
+      const sent = new Set(items.map(itemKey));
+      const missing = current.filter((m) => !sent.has(itemKey(m))).map(itemKey);
+      const foreign = items.filter((it) => !byKey2.has(itemKey(it))).map(itemKey);
+      if (missing.length > 0) lines.push(`missing from payload: ${missing.join(", ")}`);
+      if (foreign.length > 0) lines.push(`not in container: ${foreign.join(", ")}`);
+      lines.push(`payload: ${JSON.stringify(payload)}`);
+      return lines;
+    },
+    execute: async () => {
+      try {
+        await reorder(cfg.client, payload, opts);
+      } catch (err) {
+        if (isNotFoundError(err) && err instanceof Error) throw flagOffError(cfg.entityType, err);
+        throw err;
+      }
+      const where = cfg.container === null ? "root" : `folder ${cfg.container}`;
+      cfg.out.write(`Reordered ${items.length} items in ${where}.
+`);
+    }
+  });
+}
+async function runFoldersMove(cfg) {
+  const parentArg = cfg.parentId === null ? "root" : String(cfg.parentId);
+  const action = {
+    resource: "folder",
+    id: `${cfg.entityType}:${cfg.folderId}->${parentArg}`,
+    verb: "move"
+  };
+  await preflightConfirmToken(action, cfg.token);
+  const opts = { signal: cfg.signal };
+  await twoStepConfirm({
+    out: cfg.out,
+    action,
+    token: cfg.token,
+    server: cfg.serverFlag,
+    confirmCmd: `dr folders move ${cfg.folderId} --parent ${parentArg} --entity-type ${cfg.entityType} --server ${cfg.serverFlag}`,
+    describe: async () => {
+      const tree = await list9(cfg.client, cfg.entityType, opts);
+      const byId = /* @__PURE__ */ new Map();
+      const walk = (n) => {
+        byId.set(n.id, n);
+        for (const c of n.children ?? []) walk(c);
+      };
+      for (const root of tree) walk(root);
+      const names = new Map([...byId].map(([id, n]) => [id, n.name]));
+      const folder = byId.get(cfg.folderId);
+      const to = containerLabel(cfg.parentId, names);
+      if (folder === void 0) {
+        return [
+          `folder ${cfg.folderId}: not in the ${cfg.entityType} tree (wrong --entity-type, flag off, or no access) -> ${to}`
+        ];
+      }
+      return [
+        `folder ${folder.id} (${folder.name}): ${containerLabel(folder.parent_id, names)} -> ${to}`,
+        "the folder is appended at the end of the destination (Admin / Data Manager only)"
+      ];
+    },
+    execute: async () => {
+      try {
+        await move(cfg.client, cfg.folderId, cfg.parentId, opts);
+      } catch (err) {
+        if (isNotFoundError(err) && err instanceof Error) {
+          throw new Error(
+            `folder ${cfg.folderId} not found, or folders are disabled (${FOLDER_FLAGS[cfg.entityType]}): ${err.message}`
+          );
+        }
+        throw err;
+      }
+      cfg.out.write(
+        `Moved folder ${cfg.folderId} to ${parentArg === "root" ? "root" : `folder ${parentArg}`}.
+`
+      );
+    }
+  });
 }
 async function runFoldersCreate(cfg) {
   if (cfg.name === "") {
@@ -14505,6 +14824,70 @@ function registerFoldersCommand(root) {
   );
   addServerFlag(createCmd);
   addAccountFlag(createCmd);
+  const reorderCmd = cmd.command("reorder").description(
+    "Set the interleaved order of one container (two-step confirm). The order is per-user. --items sends exactly what is given; --move splices the current members and sends them all."
+  ).option(
+    "--entity-type <t>",
+    `folder entity type: ${FOLDER_ENTITY_TYPES.join(" | ")}`,
+    "dashboard"
+  ).requiredOption("--container <c>", "root | folder id").option("--items <list>", "full ordered list, e.g. folder:12,entity:87 (sent verbatim)").option("--move <kind:id>", "item to move, e.g. entity:87").option("--to-index <n>", "0-based target index for --move (past the end = last)").option("--confirm-token <token>", "Token from a prior plan run \u2014 required to actually reorder").action(
+    async (opts) => {
+      const entityType = parseEntityTypeOpt(opts.entityType ?? "dashboard");
+      const container = parseContainerOpt(opts.container, "--container");
+      const serverKey = resolveServer(opts.server);
+      const setup = await setupCall(opts.server, opts.account);
+      try {
+        await runFoldersReorder({
+          client: setup.client,
+          entityType,
+          container,
+          items: opts.items,
+          move: opts.move,
+          toIndex: opts.toIndex,
+          token: opts.confirmToken,
+          serverFlag: serverKey,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(reorderCmd);
+  addAccountFlag(reorderCmd);
+  const moveCmd = cmd.command("move").description(
+    "Move a folder under another folder or to root (two-step confirm). Appends at the end of the destination; Admin / Data Manager only."
+  ).argument("<folderId>", "folder id (positive integer)").requiredOption("--parent <p>", "root | destination folder id").option(
+    "--entity-type <t>",
+    `tree to describe the move from: ${FOLDER_ENTITY_TYPES.join(" | ")}`,
+    "dashboard"
+  ).option("--confirm-token <token>", "Token from a prior plan run \u2014 required to actually move").action(
+    async (idStr, opts) => {
+      const folderId = parseContainerOpt(idStr, "<folderId>");
+      if (folderId === null) throw new Error('invalid <folderId> "root"');
+      const parentId = parseContainerOpt(opts.parent, "--parent");
+      const entityType = parseEntityTypeOpt(opts.entityType ?? "dashboard");
+      const serverKey = resolveServer(opts.server);
+      const setup = await setupCall(opts.server, opts.account);
+      try {
+        await runFoldersMove({
+          client: setup.client,
+          entityType,
+          folderId,
+          parentId,
+          token: opts.confirmToken,
+          serverFlag: serverKey,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(moveCmd);
+  addAccountFlag(moveCmd);
 }
 
 // src/api/dynamicRanges.ts
@@ -17020,7 +17403,7 @@ async function update3(client, id, body, options) {
 async function deleteById6(client, id, options) {
   await client.deleteJSON(`/api/templates/lutdocuments/${id}`, options);
 }
-async function reorder(client, body, options) {
+async function reorder2(client, body, options) {
   await client.postJSON("/api/templates/lutdocuments/update_orders", body, options);
 }
 var LUT_SAVE_POLL_INTERVAL_MS = 2e3;
@@ -18150,7 +18533,7 @@ async function runLutReorder(cfg) {
     body = await readJsonPayload(payloadFile);
     count = Array.isArray(body["objects"]) ? body["objects"].length : 0;
   }
-  await reorder(cfg.client, body, { signal: cfg.signal });
+  await reorder2(cfg.client, body, { signal: cfg.signal });
   cfg.out.write(`Reordered ${count} lookup${plural(count)}.
 `);
 }
@@ -20116,7 +20499,7 @@ function parseDimensionFilters(raw) {
 }
 
 // src/commands/metricsCreate.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 
 // src/api/metricsMonolith.ts
 async function create9(client, body, options) {
@@ -23568,7 +23951,7 @@ async function runMetricsDelete(cfg) {
   });
 }
 function shortHash(input) {
-  return createHash3("sha256").update(input).digest("hex").slice(0, 12);
+  return createHash4("sha256").update(input).digest("hex").slice(0, 12);
 }
 function buildMetricsBatchDeleteAction(ids) {
   const sorted = [...new Set(ids)].sort((a, b) => a - b);
@@ -25381,7 +25764,7 @@ async function getOrgReportingCurrencies(client, organizationId, options) {
 }
 
 // src/commands/fxConfig.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 
 // src/api/widgets.ts
 async function list18(client, dashboardId, options) {
@@ -25944,7 +26327,7 @@ async function runFxSetPosting(cfg) {
     verb: "set-fx"
   } : {
     resource: "field-batch",
-    id: createHash4("sha256").update(
+    id: createHash5("sha256").update(
       changes.map((c) => `${c.field.id}:posting`).slice().sort().join("|")
     ).digest("hex").slice(0, 12),
     verb: "set-fx"
@@ -26398,7 +26781,7 @@ function buildSetReportingAction(changes) {
     };
   }
   const canonical = changes.map((c) => `${c.field.id}:reporting:${c.code}:${c.symbol ?? ""}`).slice().sort().join("|");
-  const sha = createHash4("sha256").update(canonical).digest("hex").slice(0, 12);
+  const sha = createHash5("sha256").update(canonical).digest("hex").slice(0, 12);
   return { resource: "field-batch", id: sha, verb: "set-fx" };
 }
 function renderReportingOutcome(out, results, skipped, notFxTables, asJson) {
@@ -27378,7 +27761,7 @@ function registerFxCommand(root) {
 }
 
 // src/commands/errorEnrichments.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import { promises as fs13 } from "fs";
 import * as path4 from "path";
 
@@ -27918,7 +28301,7 @@ async function runEnrichmentsExport(cfg) {
   requireSweepSuccess(results);
 }
 function shortHash2(input) {
-  return createHash5("sha256").update(input).digest("hex").slice(0, 12);
+  return createHash6("sha256").update(input).digest("hex").slice(0, 12);
 }
 function canonicalBatch(parts) {
   return stableJson(parts);
@@ -28713,7 +29096,7 @@ function registerErrorEnrichmentsCommand(root) {
 }
 
 // src/commands/skill.ts
-import { createHash as createHash6 } from "crypto";
+import { createHash as createHash7 } from "crypto";
 import { readFile as readFile3, mkdir as mkdir2, readdir as readdir2, rm as rm2, rmdir, stat, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname6, join as join8, resolve as resolve2 } from "path";
 
@@ -28875,7 +29258,7 @@ async function runSkillPrint(cfg) {
     throw new Error(`skill "${skill.name}" has no file "${relPath}" \u2014 available: ${available}`);
   }
   if (cfg.hash) {
-    const hex = createHash6("sha256").update(hit.bytes).digest("hex");
+    const hex = createHash7("sha256").update(hit.bytes).digest("hex");
     cfg.out.write(hex + "\n");
     return;
   }
@@ -32740,7 +33123,7 @@ async function itResync(client, id, reqOptions) {
 // src/commands/filebox.ts
 import { promises as fsPromises, existsSync as existsSync2 } from "fs";
 import * as nodePath from "path";
-import { createHash as createHash7 } from "crypto";
+import { createHash as createHash8 } from "crypto";
 
 // src/commands/filebox_admin.ts
 import { promises as fs15 } from "fs";
@@ -35369,7 +35752,7 @@ function buildIncludeBatchAction(docId, include, targets) {
   const canonical = `${docId}|${include ? "on" : "off"}|${targets.map((v) => v.id).slice().sort((a, b) => a - b).join(",")}`;
   return {
     resource: "filebox-version-batch",
-    id: createHash7("sha256").update(canonical).digest("hex").slice(0, 12),
+    id: createHash8("sha256").update(canonical).digest("hex").slice(0, 12),
     verb: includeStateWords(include).verb
   };
 }
@@ -42212,7 +42595,7 @@ function registerWidgetsCommand(root) {
 }
 
 // src/commands/reconciliation.ts
-import { createHash as createHash8 } from "crypto";
+import { createHash as createHash9 } from "crypto";
 import { promises as fs18 } from "fs";
 
 // src/api/reconciliation.ts
@@ -43839,7 +44222,7 @@ function chunkByJsonBytes(rows, maxBytes) {
   return chunks;
 }
 function settingsActionId(settings) {
-  return createHash8("sha256").update(JSON.stringify(settings)).digest("hex").slice(0, 12);
+  return createHash9("sha256").update(JSON.stringify(settings)).digest("hex").slice(0, 12);
 }
 async function runReconciliationAccountsUpdateSettings(cfg) {
   const action = {
@@ -44217,7 +44600,7 @@ async function runReconciliationAccountsSetAssignee(cfg) {
 var ASSIGNEE_BATCH_CHUNK_SIZE = 100;
 function assigneeBatchActionId(date, rows) {
   const canonical = rows.map((r) => [r.accountId, r.type, r.userId, r.userName, r.userEmail]);
-  return createHash8("sha256").update(JSON.stringify([date, canonical])).digest("hex").slice(0, 12);
+  return createHash9("sha256").update(JSON.stringify([date, canonical])).digest("hex").slice(0, 12);
 }
 async function runReconciliationAccountsSetAssigneeBatch(cfg) {
   const action = {
@@ -44371,7 +44754,7 @@ verify the date matches the accounts' reporting period (try \`dr reconciliation
 }
 function clearBatchActionId(date, rows) {
   const canonical = rows.map((r) => [r.accountId, r.type]);
-  return createHash8("sha256").update(JSON.stringify(["clear", date, canonical])).digest("hex").slice(0, 12);
+  return createHash9("sha256").update(JSON.stringify(["clear", date, canonical])).digest("hex").slice(0, 12);
 }
 async function runReconciliationAccountsClearAssigneeBatch(cfg) {
   const action = {
@@ -46261,7 +46644,7 @@ function renderForError(v) {
 }
 
 // src/commands/mecWorkflow.ts
-import { createHash as createHash9 } from "crypto";
+import { createHash as createHash10 } from "crypto";
 
 // src/api/workflow.ts
 function buildQueryString(params) {
@@ -48312,7 +48695,7 @@ async function runMecAccountsTaskStatuses(cfg) {
   renderMecAccountsTasksOrStatuses(cfg.out, resp, "statuses");
 }
 function shortHash3(input) {
-  return createHash9("sha256").update(input).digest("hex").slice(0, 12);
+  return createHash10("sha256").update(input).digest("hex").slice(0, 12);
 }
 async function runMecWorkflowCreate(cfg) {
   const action = {
@@ -50696,7 +51079,7 @@ function wireMec(program) {
 }
 
 // src/commands/workflow.ts
-import { createHash as createHash10 } from "crypto";
+import { createHash as createHash11 } from "crypto";
 function dash6(s) {
   if (s === null || s === void 0) return "-";
   if (typeof s === "number") return String(s);
@@ -51165,7 +51548,7 @@ function renderGroupList(out, rows) {
 `);
 }
 function shortHash4(input) {
-  return createHash10("sha256").update(input).digest("hex").slice(0, 12);
+  return createHash11("sha256").update(input).digest("hex").slice(0, 12);
 }
 async function runWorkflowCreate(cfg) {
   const action = {
@@ -53324,7 +53707,7 @@ function wireWorkflow(root) {
 }
 
 // src/commands/cash.ts
-import { createHash as createHash11 } from "crypto";
+import { createHash as createHash12 } from "crypto";
 import { promises as fs25 } from "fs";
 
 // src/api/cash.ts
@@ -54415,7 +54798,7 @@ async function runCashRulesDeleteAll(cfg) {
     return;
   }
   const ids = targets.map((r) => r.id).sort((a, b) => a - b);
-  const sha = createHash11("sha256").update(ids.join(",")).digest("hex").slice(0, 12);
+  const sha = createHash12("sha256").update(ids.join(",")).digest("hex").slice(0, 12);
   const action = {
     resource: "cash-rules-batch",
     id: `${templateId}:${sha}`,

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.100",
+  "cliVersion": "1.6.102",
   "_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": {
@@ -635,6 +635,22 @@
         }
       ]
     },
+    "folders reorder": {
+      "requires": [
+        {
+          "resource": "dashboards",
+          "action": "write"
+        }
+      ]
+    },
+    "folders move": {
+      "requires": [
+        {
+          "resource": "dashboards",
+          "action": "write"
+        }
+      ]
+    },
     "dynamic-ranges list": {
       "requires": [
         {

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

@@ -244,7 +244,10 @@ area's gotchas.
   subcommand.
 
 **Dashboards, widgets, storyboards, reports, extables** → [reference/dashboards-widgets.md](reference/dashboards-widgets.md)
-- `dashboards list|get|create|delete|prepare|set-date-picker`
+- `dashboards list|get|create|delete|prepare|set-date-picker|set-folder`
+- `folders list|create|reorder|move` — dashboard / story picker folders;
+  `reorder` and `move` are two-step confirm. Reorder is per-user and takes the
+  container's full member set (`folders list` shows it).
 - `dashboards push <id> --to <orgs> [--override]` — copy a dashboard into other
   organizations (two-step confirm). Destinations must come from
   `organizations push-targets`.

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

@@ -34,6 +34,29 @@ dashboard is added, with `' Copy'` appended if the name is taken.
 The push is queued and returns no job id — results arrive as in-app
 notifications. Confirm with `dashboards list --account <destination>`.
 
+### Folders (picker tree)
+
+Gated per entity type by Unleash `dashboards__folders` / `storytelling__folders`.
+Flag off: `folders list` shows no tree and says the flag is off; every write 404s.
+
+- `folders list [--entity-type dashboard|story]` — the tree, then each
+  container's members in picker order as `kind:id name position` (`root` first).
+  This is the input for a reorder. `--json` is the raw tree only.
+- `folders create --name <n> [--parent <id>]`.
+- `folders reorder --container <root|folderId> (--items folder:12,entity:87,… | --move <kind:id> --to-index <n>)`
+  — two-step confirm. The order is **per user**, and the server takes only the
+  FULL set of the container's members visible to the caller, so anything partial,
+  foreign or duplicated is a 400. `--move` fetches the current members, splices
+  the item in (an index past the end lands it last) and sends them all.
+  `--items` is sent exactly as given, which is how you reproduce a 400; the plan
+  lists what is missing from the payload and what is not in the container. The
+  400 body is printed verbatim.
+- `folders move <folderId> --parent <root|folderId>` — two-step confirm.
+  Re-parents the folder and appends it at the destination's end. Admin / Data
+  Manager only.
+- `dashboards set-folder <id> (--folder <fid> | --root)` moves a dashboard
+  (`PUT /api/dashboards/<id>` `{folder_id}`). It is appended at the end.
+
 ## Widgets
 
 - `widgets list`, `widgets get <id>`, `widgets data <id>` (alias `widget`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.100",
+  "version": "1.6.102",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.10.21",
+    "@datarails-ai/dr-appspace-cli": "0.10.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",