@datarails-ai/dr-cli 1.6.105 → 1.6.106

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.105",
+  "cliVersion": "1.6.106",
   "_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": {
@@ -739,6 +739,26 @@
         }
       ]
     },
+    "functions data": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "read"
+        }
+      ]
+    },
+    "functions drilldown": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "read"
+        },
+        {
+          "resource": "dashboards",
+          "action": "read"
+        }
+      ]
+    },
     "functions delete": {
       "requires": [
         {

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

@@ -239,7 +239,11 @@ area's gotchas.
 - `metrics suggestions list|refresh` + `metrics dimensions suggestions list|refresh` — AI suggestion agents (list shows suggestions + `last_run` status; `refresh` triggers a run, `--wait [--timeout <s>]` polls to completion). Gated per-org by Unleash flags; a successful `metrics migrate` auto-triggers both agents, so a 409 from `refresh` right after usually means it's already running — check `list`.
 - `metrics suggestions profile` — read-only: profiles every table and returns, per table, the `reporting_axis` (WHICH date column a BASE metric should bucket by, with `chosen_by` naming the rule), `row_grain.reads_as` (`movements` -> time_aggregation SUM, `balances` -> EOP), candidate `measures`, `categoricals`, and the metrics already defined there. Use this BEFORE proposing any metric: `date_field` cannot be read off the payload (no field marks the reporting column) and guessing it produces a silently wrong number that passes validation. `reporting_axis: null` and `reads_as: "unknown"` are real answers - do not substitute a guess. All measure statistics are SAMPLED from storage-ordered windows and named `sampled_*`; there is deliberately no sum/avg. Needs no Unleash flag. ~30s and ~230 requests on a 43-table org.
 - `metrics dimensions suggestions profile` — read-only: profiles every table/field and returns scored candidate dimension groups (value-overlap grouping, existing-dimension dedupe, machine-readable rejection reasons) in ONE call. Use this instead of looping `templates distinct` per field when reasoning about what dimensions an org should have. Needs no Unleash flag. `--json` for the payload, `--out <file>` when only `summary`/`groups` matter, `--suppression <file>` when you already hold the existing-dimension and dismissed lists. Also emits `near_misses` — pairs just under the merge threshold, for you to judge rather than silently dropped.
-- `functions list|get|create|update|delete|set-filters` — a function's **definition** only.
+- `functions list|get|create|update|delete|set-filters` — a function's **definition**.
+- `functions data <id> --filter "F=V1,V2" --date "Reporting Date=2025-01-31" [--agg YTD]` — the
+  function's **live value**, computed by the same endpoint the Excel add-in uses for
+  `DR.GET`/`DR.YTD`; `functions drilldown <id> … [--out rows.csv]` — the rows behind it.
+  `create`/`update --date-field <Date field>` is required for YTD/QTD/MTD to work.
   - _`set-filters <id> --file <json> [--confirm]` is the **only** way to author a
     function's row-level filters (create/update don't touch them). FULL REPLACE —
     an empty array clears all; dimension `values` are a plain list, date filters

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

@@ -478,11 +478,10 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
     51-table org. Read `summary.empty_unverified` as "at least this many
     fields' emptiness is unproven", not as an exact census.
 
-## Functions (DR.GET definitions)
+## Functions (DR.GET definitions and values)
 
 - `functions list`, `functions get <id>` — `get` returns the **definition**,
-  **not** the live value. Live function values are computed in Excel via
-  `DR.GET(...)` through the add-in and are not exposed by this CLI.
+  not the value (for the value see `functions data` below).
   - The core row is `id / name / agg / template / value_field`; below it `get`
     prints a **FILTERS** section (one row per persisted filter: `field`, `name`,
     `type`, `excluded`, `values`) and the **default agg date field** when set.
@@ -492,6 +491,18 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
     blob (owned by the add-in), shown verbatim as compact JSON — read it there
     rather than asking the customer to re-check the UI.
 - `functions create`, `functions update`, `functions delete` (two-step confirm).
+  - `--date-field <id|name>` (create and update) sets the function's **default
+    aggregation date field** (must be a Date field of the template) and sends the
+    platform's default per-period roll-up config (every period by month, `sum`,
+    end-of-period — what UI-created functions carry; a function needing MTD by
+    day must be adjusted in the UI). **Without it `DR.YTD`/`QTD`/`MTD`/…
+    do not work for the function anywhere** — `functions data --agg YTD` answers
+    HTTP 400 `{"DateAgg":[…]}` and the xlsx auto-calculate engine fails outright.
+    `create` without it prints a one-line warning on stderr. A later
+    `update`/`set-filters` full PUT keeps the date field (verified) — so
+    `update --template <id>` on a function that has one is **refused unless
+    `--date-field` is passed too** (the old field belongs to the old table, and
+    the server checks only its type).
 - `functions set-filters <id> --file <json> [--confirm]` — **the only way to
   author a function's filters** (`create`/`update` don't touch them). **FULL
   REPLACE**: the server deletes every existing filter and recreates from the
@@ -505,6 +516,65 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
   `--confirm`; internally a read-modify-write PUT that preserves the core fields
   and calculated-value links.
 
+### Live values: `functions data`
+
+`functions data <id> [--filter "NAME=V1,V2"]… [--date "NAME=DATE[,DATE]"]… [--agg DEFAULT|YTD|YTG|QTD|QTG|MTD|MTG] [--json]`
+evaluates the function through `PUT /api/functions/<id>/data/v2` — the endpoint
+the Excel add-in calls for `DR.GET` (`--agg DEFAULT`) and `DR.YTD`/… — so the
+number is the one Excel shows, with the function's own filters always applied
+(a `--filter` can only narrow them, never override).
+
+- Fields are named (or given by id) and resolved on the function's template;
+  the add-in's canonical field name goes on the wire. An unknown field fails
+  client-side with the list of valid fields.
+- **Dates.** The endpoint wants **Excel serial numbers** (2025-01-31 = 45688);
+  epoch seconds and ISO strings are not rejected server-side, they silently
+  return nothing. The CLI converts: on a Date field (via `--date` or `--filter`)
+  pass `YYYY-MM-DD`, `M/D/YYYY`, an ISO datetime, a serial, or epoch seconds.
+  A bare month (`2025-06`) is **refused** — tables store a specific day
+  (usually month-END), so a month's 1st would match nothing (DEFAULT) or stop a
+  month short (YTD). Pass the stored day, e.g. `2025-06-30`.
+- Several values on one field return **one row per value combination**; the
+  table shows each field's key (serials rendered back as dates) and `VALUE`
+  (rounded to 4 decimals for display; `--json` is the server body verbatim).
+- No row at all prints `(no data: nothing matches these filters)` — a real
+  answer (unknown value, or the function's own filter excludes it), not an error.
+- Errors: a per-query `error.msg` (e.g. "Field X is not related to function")
+  and any non-2xx exit non-zero; an HTTP 400 such as
+  `{"DateAgg":["Function N has no default aggregation date field"]}` is shown
+  verbatim with the `--date-field` fix. Under `--json` the body is printed first.
+
+### Rows behind a value: `functions drilldown`
+
+`functions drilldown <id> [--filter …]… [--exclude …]… [--date …]… [--agg …] [--columns a,b] [--limit 20] [--out rows.csv] [--csv] [--json]`
+calls `PUT /api/functions/<id>/drilldown/v4` with the same filters (as the
+add-in's filter objects, field id + type resolved from the template).
+
+- Prints `N rows × M columns`, the function's own aggregate over those rows
+  (`SUM(Amount) over these rows: …` — equals `functions data` with the same
+  filters), then the first `--limit` rows (0 = all) of the filtered fields and
+  the value field, or of `--columns`. Date columns arrive as epoch seconds and
+  are shown as dates.
+- Above the server's inline cap (≈ tens of thousands of rows) the answer is
+  `too_large_data`. Without `--out` that is an error naming the size; narrow
+  with more `--filter`s or add `--out`. With `--out <file.csv>` the CLI takes
+  the add-in's **CSV export** path automatically (`export_to_csv` → cache-key
+  poll → report download, ~15 s for 25k rows × 215 columns, 20 MB); `--csv`
+  forces it. An inline answer with `--out` is written as CSV too (schema
+  columns, dates as `YYYY-MM-DD`). `--out` raises the command budget to 300 s
+  (`--timeout <s>` overrides).
+- `--json` prints the inline body verbatim (rows plus a trailing
+  `{fields, empty_fields}` schema object); with `--out`, a JSON summary
+  (`source`, `rows`, `columns`, `aggregate`, `report_id`).
+- **Credential scopes:** a scoped credential (API key) needs `tables:read`
+  **and `dashboards:read`** for `drilldown`. The CSV export path polls
+  `/api/cache/cache_keys_status` and downloads `/api/dashboards/report/<n>`,
+  both of which the server scopes to `dashboards`; without it the export fails
+  at the first status poll (error 40301) after the server has started the task.
+  The CLI declares `dashboards:read` for every drill-down, inline included,
+  because scopes are per command, not per flag. `functions data` needs
+  `tables:read` only.
+
 ## Customer-facing docs (KB)
 
 Help Center → the **"Semantic Layer"** category. Find current articles with `dr kb search "metric KPI"` (or

package/package.json

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