@datarails-ai/dr-cli 1.6.136 → 1.6.137

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.136",
+  "cliVersion": "1.6.137",
   "_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": {
@@ -1031,6 +1031,14 @@
         }
       ]
     },
+    "reports update": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "write"
+        }
+      ]
+    },
     "reports delete": {
       "requires": [
         {
@@ -1127,6 +1135,14 @@
         }
       ]
     },
+    "metrics create driver": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "write"
+        }
+      ]
+    },
     "metrics categories list": {
       "requires": [
         {
@@ -1303,6 +1319,78 @@
         }
       ]
     },
+    "metrics driver get": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "read"
+        }
+      ]
+    },
+    "metrics driver set": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "write"
+        }
+      ]
+    },
+    "metrics driver delete": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "destructive"
+        }
+      ]
+    },
+    "metrics driver values get": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "read"
+        }
+      ]
+    },
+    "metrics driver values set": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "write"
+        }
+      ]
+    },
+    "metrics calculations list": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "read"
+        }
+      ]
+    },
+    "metrics calculations add": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "write"
+        }
+      ]
+    },
+    "metrics calculations remove": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "write"
+        }
+      ]
+    },
+    "metrics what-if": {
+      "requires": [
+        {
+          "resource": "metrics",
+          "action": "read"
+        }
+      ]
+    },
     "fx set-posting": {
       "requires": [
         {

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

@@ -234,7 +234,8 @@ area's gotchas.
 
 **Metrics (KPIs) & functions** → [reference/metrics.md](reference/metrics.md)
 - `metrics list|get|data|drilldown`
-- `metrics create base|calc`, `metrics update|delete`
+- `metrics create base|calc|driver`, `metrics update|delete`
+- `metrics driver get|set|delete`, `metrics driver values get|set`, `metrics calculations list|add|remove`, `metrics what-if`: drivers, scenario-bound formulas and what-if runs, addressed per scenario context (`--scenario` / `--cycle` / `--planning-scenario`, matched exactly)
 - `metrics re-aggregate` — rebuild pre-aggregated metric values (targeted ids, or `--all` org-wide); add `--wait [--timeout <s>]` on targeted ids to block until done (exits non-zero on failure/timeout)
 - `metrics migrate` — org-wide metrics+dimensions migration (V1→V2 backfill; `--dry-run` first)
 - `metrics categories list|get|create|update|delete`
@@ -271,7 +272,7 @@ area's gotchas.
   default so results match the product UI; `--no-dashboard-context` computes
   from the widget's own settings only.
 - `storyboards list|get|slides|prepare|delete`
-- `reports list|get|clone|delete`
+- `reports list|get|clone|update|delete` — `update <id>` edits a Financials (Report Builder) report: `--payload-file` (payload keys, or `reports get --json` output), `--name`, `--option k=v`, `--date-picker-preset`; dry-run unless `--confirm`
 - `extables list|get|clone|delete`
 
 **Budget Builder (Budget management templates)** → [reference/budget-builder.md](reference/budget-builder.md)

package/dist/skills/dr-cli/reference/budget-builder.md

@@ -20,7 +20,13 @@ Commands:
 - `budget-builder add-row` — validate, then merge the row and rebuild
   (`--out-file` writes the updated definition for a later `save`).
 - `budget-builder save --payload-file <f>` — persist to Budget management
-  (new template → `id: -1` in the payload).
+  (new template → `id: -1` in the payload). On large-report orgs the server
+  answers 409 while a worker saves; the CLI polls with the returned
+  cache_key for up to `--timeout <ms>` (default 60000). On timeout, check
+  `dr reports list` before re-running save — a second save creates a
+  second report.
+- `reports update` refuses budget reports (it edits Financials reports
+  only).
 - `documents split create|list|status|undo` — split a saved budget file into
   per-dimension-value child files (see
   [reference/filebox-documents.md](filebox-documents.md) for the documents

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

@@ -104,6 +104,30 @@ Flag off: `folders list` shows no tree and says the flag is off; every write 404
 - `storyboards list|get|slides`; `storyboards prepare`, `storyboards delete`
   (two-step confirm).
 - `reports list|get`; `reports clone`, `reports delete` (two-step confirm).
+- `reports update <id>` — edit a **Financials** (Report Builder) report.
+  Budget reports are refused (the CLI cannot edit them in place).
+  - Inputs: `--payload-file <f>` (a JSON object of payload keys, or the
+    whole `reports get <id> --json` output — its `.payload` is used),
+    `--name`, `--option k=v` (repeatable, merged into the stored `options`),
+    `--date-picker-preset today|yesterday|this_month|prev_month`.
+  - The server merges the body over the stored payload: a top-level key
+    REPLACES the stored one (`rows`, `cols`, `options`, … are whole values).
+    The CLI sends only keys whose value differs from the stored report.
+  - Dry-run by default (prints the changed keys); `--confirm` sends the PUT.
+    Relay the dry-run to the user before confirming.
+  - Keep `document_data` / `report_space_data` / `workflow_data` OUT of the
+    payload file unless the user asks to link a file: the platform stores
+    them and regenerates the linked file on every later save. The CLI warns
+    when the file sets one.
+  - Exits non-zero when the server saved the report but returned
+    `generated_report_details.error`.
+  - Large reports: see "Large-report writes" below.
+- **Large-report writes** (`reports update`, `budget-builder save`): on orgs
+  with large-reports support the server answers 409 `{cache_key}` while a
+  worker runs the write, and the CLI re-sends the same request with that
+  key for up to `--timeout <ms>` (default 60000). On timeout the write may
+  still land — check `reports get <id>` (update) or `reports list` (save)
+  before retrying; a second `save` creates a second report.
 - `extables list|get`; `extables clone`, `extables delete` (two-step confirm).
   To inject an ExTable's data into a raw `.xlsx`, that's `documents add-extables`
   (see reference/filebox-documents.md), **not** an `extables` subcommand.

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

@@ -10,8 +10,9 @@
   field (`--json | jq '.presented_formula'` returns null; read
   `.configuration.presented_formula`).
 - `metrics data --id <id> --scenario Actuals --from 2026-01-01 --to 2026-12-31` —
-  the KPI value over a range. `--scenario` / `--cycle` are repeatable and also
-  accept comma-separated values (e.g. `Actuals,Budget`) to pull several at once.
+  the KPI value over a range. `--scenario` / `--cycle` / `--planning-scenario` are
+  repeatable and also accept comma-separated values (e.g. `Actuals,Budget`) to
+  pull several at once.
   - `--period <day|month|quarter|year>` (default `month`) sets the grain of the
     returned buckets.
   - `--agg <DEFAULT|MTD|QTD|YTD|MTG|QTG|YTG>` (default `DEFAULT`) sets how each
@@ -109,6 +110,66 @@ Required: `--name`, `--template <id>`, `--value-field <id>`, `--date-field <id>`
   order-independent and de-duplicated. A failed id doesn't abort the batch: each
   outcome is reported and the command exits non-zero if any delete failed.
 
+## Drivers, scenario calculations, what-if
+
+Planning-model commands. The server gates them behind the
+`scenario_bound_calculations` flag and a planning product (budget or forecast
+cycle management). When either is off it answers 400/403/405 with a message,
+and the CLI prints that message unchanged.
+
+**Scenario context.** `driver …` and `calculations add|remove` address one
+context with `--scenario <name>` (default `Actuals`), `--cycle <label>` and
+`--planning-scenario <name>`. All three are free-text names and must match
+exactly. A context never inherits from another one, so a driver set under
+`Budget` is a different row from the `Actuals` one.
+
+- `metrics create driver --name <n> [--description] [--category <id>]
+  [--dimensions <ids>]` creates a DRIVER metric. It has no table, value or
+  date field and no formula.
+- `metrics driver get <id> [ctx]` shows the definition: unit, additive,
+  baseline, min, max and grain dimension. When the context has no driver the
+  command exits non-zero with "no driver for metric … in context …".
+- `metrics driver set <id> [ctx] [--unit <s>] [--additive | --non-additive]
+  [--baseline <n|null>] [--min <n|null>] [--max <n|null>]
+  [--grain-dimension <dimId|null>]` creates the context's row if it is
+  missing. Only the flags you pass are sent, and omitted fields keep their
+  stored values. `null` clears baseline, min, max or grain, and `--unit ""`
+  clears the unit. The command refuses to run with no field flag. The server
+  rejects min > max, and it refuses a grain change while values exist.
+- `metrics driver delete <id> [ctx]` deletes the context's driver and all of
+  its values. It uses the two-step confirm, and the token is bound to the
+  context.
+- `metrics driver values get <id> [ctx]` prints a MEMBER / PERIOD / VALUE
+  table, with `(default)` for a member's null-period default.
+- `metrics driver values set <id> [ctx] --file <grid.csv|grid.json>`
+  **replaces the whole grid**: any cell not in the file is deleted. The CSV
+  header is `member,period,value`. Period is `YYYY-MM` or `YYYY-MM-01`, or
+  empty for the member's default. An empty value means null. Member is empty
+  when the driver has no grain. A JSON file is `{"values": [...]}` or a bare
+  array. The CLI checks the 20,000-cell cap and duplicate (member, period)
+  cells before sending. The driver must already exist for the context, so run
+  `driver set` first.
+- `metrics calculations list <id>` lists the scenario-bound formulas of a CALC
+  metric. `calculations add <id> [ctx] --formula "[A] * [B]"` uses the same
+  syntax as `create calc`. It reads the list, appends the new formula, and
+  writes the full list back. If the context already has a formula it refuses,
+  unless you pass `--replace`. `calculations remove <id> [ctx]` uses the
+  two-step confirm, and the plan shows the formula being removed. Only CALC
+  metrics accept calculations. The server rejects duplicate contexts and
+  formula loops.
+- `metrics what-if --formula "[Headcount] * [Avg Salary]" [--driver
+  Headcount=15]… [--driver-file overrides.json] [--reference-month YYYY-MM]
+  [--time-aggregation SUM|AVG|EOP] [--dimension <dimName>]…` evaluates the
+  formula over the 3 months ending at the reference month (default: the
+  current month). The overrides apply to this call only and nothing is saved.
+  It prints the combined result, then one contribution block per overridden
+  driver. The driver file maps each driver name to
+  `{"baseline_value": n|null, "values": [{member, period, value}]}`. A
+  `--driver` flag overrides that driver's baseline from the file. The limit is
+  20 drivers. The server ignores a driver that is not an operand of the
+  formula, so the CLI prints a warning on stderr for any driver name that
+  does not appear in the formula.
+
 ## Re-aggregate (`metrics re-aggregate`)
 
 Manually trigger the semantic-layer pipeline that rebuilds pre-aggregated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.136",
+  "version": "1.6.137",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {