mammoth-cli 2.0.13__tar.gz → 2.0.14__tar.gz

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.13
+Version: 2.0.14
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.8,>=0.7.5
+Requires-Dist: mammoth-io<0.8,>=0.7.6
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.0.13"
+__version__ = "2.0.14"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -65,6 +65,9 @@ the result.
 - **Import, resources, transforms, pipelines, dashboards, exports, or cleanup:**
   [recipes](references/recipes/index.md) and [operations](references/operations.md)
 - **A known command family or exact command:** [command catalog](references/command-index.md)
+- **Whether a route is proven, known-blocked, or untried on release:**
+  [capabilities](references/capabilities.md) — read it before promising a
+  deliverable or reporting a failure as a backend fault
 - **Pause or transfer to another agent:** [handoff](references/handoff.md)
 
 ## Handoff checklist

mammoth_cli-2.0.14/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -0,0 +1,220 @@
+# What is proven on release
+
+Generated from `docs/release-capability-matrix.json`; do not edit by hand.
+455 API operations have a CLI command. 142 were exercised successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID --output json --no-input`, run it, and treat the structured error envelope as the answer.
+
+Status meanings:
+
+- **verified**: one bounded live run on release returned a success envelope (single path; variants and error paths are usually untested).
+- **not supported**: the backend refuses the route on release; the note says why and what to use instead.
+- **observed blocker**: the last run hit an error; the note quotes it. Re-check before relying on the route, and do not retry the same input.
+- **CLI defect fixed, untried since**: the failure was on the CLI side and this release repairs it; nobody has re-run the route yet.
+- Commands not listed under a family are untried.
+
+The typed `view transform *` commands all submit through `view.task.add`; its row below carries the transformations proven end to end (filter, fill-missing, join, pivot with an exported summary). A transformation not named there has the same untried status as any other command.
+
+## Coverage by family
+
+| Family | Commands | Verified | Not supported | Untried |
+|---|---|---|---|---|
+| `dashboard` | 104 | 66 | 2 | 36 |
+| `view` | 62 | 22 | 0 | 40 |
+| `support` | 45 | 0 | 0 | 45 |
+| `billing` | 23 | 0 | 0 | 23 |
+| `connector` | 22 | 2 | 0 | 20 |
+| `workspace` | 19 | 6 | 0 | 13 |
+| `project` | 17 | 5 | 0 | 12 |
+| `workflow` | 16 | 5 | 0 | 11 |
+| `dataset` | 15 | 9 | 0 | 6 |
+| `parameter` | 14 | 2 | 0 | 12 |
+| `data-app` | 12 | 1 | 0 | 11 |
+| `folder` | 8 | 5 | 0 | 3 |
+| `snippet` | 8 | 1 | 0 | 7 |
+| `automation` | 7 | 1 | 0 | 6 |
+| `user` | 7 | 2 | 0 | 5 |
+| `webhook` | 7 | 0 | 0 | 7 |
+| `addon` | 6 | 0 | 0 | 6 |
+| `batch` | 6 | 2 | 0 | 4 |
+| `file` | 6 | 3 | 0 | 3 |
+| `agent` | 5 | 1 | 0 | 4 |
+| `ai` | 5 | 0 | 0 | 5 |
+| `annotation` | 5 | 1 | 0 | 4 |
+| `client-app` | 5 | 0 | 0 | 5 |
+| `notification` | 5 | 1 | 0 | 4 |
+| `schedule` | 5 | 0 | 0 | 5 |
+| `template` | 5 | 0 | 0 | 5 |
+| `browse` | 4 | 2 | 0 | 2 |
+| `external-key` | 4 | 0 | 0 | 4 |
+| `trash` | 3 | 1 | 0 | 2 |
+| `activity` | 2 | 1 | 0 | 1 |
+| `job` | 2 | 2 | 0 | 0 |
+| `report` | 1 | 1 | 0 | 0 |
+
+## `activity`
+
+Verified: `activity.list`
+
+| Command | State | Note |
+|---|---|---|
+| `activity.export` | observed blocker | server_error: see sweep report |
+
+## `agent`
+
+Verified: `agent.session.list`
+
+## `ai`
+
+| Command | State | Note |
+|---|---|---|
+| `ai.sql.generate` | observed blocker | validation_error: HTTP 400 Validation error |
+| `ai.suggestion.list` | observed blocker | validation_error: HTTP 400 Validation error |
+
+## `annotation`
+
+Verified: `annotation.list`
+
+## `automation`
+
+Verified: `automation.list`
+
+## `batch`
+
+Verified: `batch.get`, `batch.list`
+
+## `browse`
+
+Verified: `browse.project`, `browse.workspace`
+
+| Command | State | Note |
+|---|---|---|
+| `browse.folder` | observed blocker | cli_error: rejects folder id 0 although folder.root reports id 0 as the root |
+| `browse.root` | observed blocker | server_error: see sweep report |
+
+## `connector`
+
+Verified: `connector.active`, `connector.list`
+
+| Command | State | Note |
+|---|---|---|
+| `connector.ai.session.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+| `connector.connection.list` | observed blocker | server_error: see sweep report |
+| `connector.get` | observed blocker | validation_error: HTTP 400 'Invalid connector key' for a key returned by connector.list |
+
+## `dashboard`
+
+Verified: `dashboard.analytics`, `dashboard.cancel-generation`, `dashboard.canvas.get`, `dashboard.canvas.restore`, `dashboard.chat.edit`, `dashboard.chat.history`, `dashboard.context.create`, `dashboard.context.delete`, `dashboard.context.extract`, `dashboard.context.list`, `dashboard.context.update`, `dashboard.create-blank`, `dashboard.delete`, `dashboard.descriptor-data`, `dashboard.duplicate`, `dashboard.exemplar.extract`, `dashboard.get`, `dashboard.get-by-url`, `dashboard.list`, `dashboard.page.plan`, `dashboard.pages.add`, `dashboard.qa.ask`, `dashboard.qa.comment.create`, `dashboard.qa.comment.delete`, `dashboard.qa.feedback`, `dashboard.qa.session.create`, `dashboard.qa.session.delete`, `dashboard.qa.session.fork`, `dashboard.qa.session.get`, `dashboard.qa.session.list`, `dashboard.qa.session.rename`, `dashboard.qa.session.set-visibility`, `dashboard.qa.settings.get`, `dashboard.qa.settings.set`, `dashboard.restore`, `dashboard.rls.assignment.list`, `dashboard.rls.assignment.set`, `dashboard.rls.column.list`, `dashboard.rls.value.list`, `dashboard.signature.create`, `dashboard.signature.delete`, `dashboard.signature.list`, `dashboard.signature.update`, `dashboard.style.custom.create`, `dashboard.style.custom.delete`, `dashboard.style.custom.list`, `dashboard.style.custom.update`, `dashboard.style.extract-brand`, `dashboard.style.preset.list`, `dashboard.style.token.list`, `dashboard.suggestion.list`, `dashboard.swap-data`, `dashboard.tags.delete`, `dashboard.tags.list`, `dashboard.tags.merge`, `dashboard.tags.rename`, `dashboard.tags.set`, `dashboard.template.fit`, `dashboard.template.list`, `dashboard.template.preview`, `dashboard.template.resolve-mapping`, `dashboard.templates.pending`, `dashboard.trash`, `dashboard.update`, `dashboard.v3.generate`, `dashboard.video-state`
+
+| Command | State | Note |
+|---|---|---|
+| `dashboard.create` | not supported | Not supported on release: backend returns HTTP 409 4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED (legacy dashboard creation retired). Use dashboard.create-blank or dashboard.v3.generate. Dashboard sweep 2026-09-18, CLI 2.0.12. |
+| `dashboard.pdf.export` | not supported | Not supported from the CLI on release: backend HTTP 400 4GENR001 requires params.data to be the browser-hydrated DashboardData map and states it cannot rebuild it from stored descriptors (dashboard sweep and Haiku e2e, 2026-09-18). The route works only with a client render pass. |
+| `dashboard.pdf-artifact` | observed blocker | blocked_missing_fixture: No real pdf export job_id obtainable (dashboard.pdf.export is itself blocked_missing_fixture) |
+| `dashboard.published.canvas` | observed blocker | blocked_missing_fixture: HTTP 404 4DASH001 DASHBOARD_NOT_FOUND via url endpoint: D=52 was never actually published (was_published=false); the only publish mechanism is 'dashboard s |
+| `dashboard.source.list` | observed blocker | server_error: HTTP 500 on GET /dashboards/sources; matches documented B04 SERVER_VARIANCE precondition |
+| `dashboard.video.export` | observed blocker | validation_error: HTTP 400 4GENR001: 'publish the dashboard before exporting a video' -- clear, actionable message |
+| `dashboard.widget-data` | observed blocker | blocked_missing_fixture: HTTP 409 4DASH004 DASHBOARD_WRONG_ENGINE: widget-data is a legacy-engine-only endpoint |
+| `dashboard.archive` | CLI defect fixed, untried since | 2.0.14 accepts the non-object 200 body and reports the committed state |
+| `dashboard.canvas.save` | CLI defect fixed, untried since | 2.0.14 no longer redacts style_tokens, so the canvas get -> save round-trip is intact |
+| `dashboard.data.draft` | CLI defect fixed, untried since | 2.0.14 / SDK 0.7.6 send the WidgetDataSpec params envelope (widget_id) |
+| `dashboard.data.published` | CLI defect fixed, untried since | 2.0.14 / SDK 0.7.6 send the WidgetDataSpec params envelope (widget_id) |
+| `dashboard.figure-intent` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+| `dashboard.og-card` | CLI defect fixed, untried since | SDK 0.7.5 returns a described binary body |
+| `dashboard.query` | CLI defect fixed, untried since | 2.0.14 example carries a descriptor with kind=scalar |
+| `dashboard.style.default.get` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+| `dashboard.style.derive` | CLI defect fixed, untried since | 2.0.14 no longer redacts styleTokens |
+| `dashboard.template.get` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+
+## `data-app`
+
+Verified: `data-app.list`
+
+## `dataset`
+
+Verified: `dataset.batch-data`, `dataset.create`, `dataset.data`, `dataset.delete`, `dataset.file-settings.get`, `dataset.file-settings.update`, `dataset.get`, `dataset.list`, `dataset.trash`
+
+## `external-key`
+
+| Command | State | Note |
+|---|---|---|
+| `external-key.list` | observed blocker | cli_error: not_authenticated although the same session authenticated elsewhere |
+
+## `file`
+
+Verified: `file.get`, `file.list`, `file.upload`
+
+## `folder`
+
+Verified: `folder.create`, `folder.delete`, `folder.get`, `folder.list`, `folder.update`
+
+## `job`
+
+Verified: `job.get`, `job.get-many`
+
+## `notification`
+
+Verified: `notification.list`
+
+## `parameter`
+
+Verified: `parameter.group.list`, `parameter.list`
+
+## `project`
+
+Verified: `project.checkpoint.list`, `project.data-check.list`, `project.list`, `project.pending-changes`, `project.resource-status`
+
+| Command | State | Note |
+|---|---|---|
+| `project.publish-credentials` | observed blocker | cli_error: requires odbc_type, not discoverable read-only |
+| `project.resource-dependencies` | observed blocker | cli_error: required resource_ids has no CLI flag |
+
+## `report`
+
+Verified: `report.list`
+
+## `schedule`
+
+| Command | State | Note |
+|---|---|---|
+| `schedule.list` | observed blocker | validation_error: HTTP 400 with message 'Not implemented' |
+
+## `snippet`
+
+Verified: `snippet.list`
+
+## `template`
+
+| Command | State | Note |
+|---|---|---|
+| `template.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+
+## `trash`
+
+Verified: `trash.list`
+
+## `user`
+
+Verified: `user.get`, `user.preference.get`
+
+## `view`
+
+Verified: `view.active-user.list`, `view.checkpoint.list`, `view.conditional-format.list`, `view.create`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.derivative.list`, `view.export.list`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.get`, `view.pipeline.items`, `view.preview`, `view.task.add`, `view.task.get`, `view.task.list`, `view.version.get`, `view.version.list`
+
+| Command | State | Note |
+|---|---|---|
+| `view.ai.generation-info` | observed blocker | validation_error: HTTP 400 with message 'Not implemented' |
+
+## `webhook`
+
+| Command | State | Note |
+|---|---|---|
+| `webhook.list` | observed blocker | cli_error: api_error with no HTTP status recorded |
+
+## `workflow`
+
+Verified: `workflow.graph`, `workflow.list`, `workflow.workspace-datasets`, `workflow.workspace-exports`, `workflow.workspace-sources`
+
+## `workspace`
+
+Verified: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.storage-breakdown`, `workspace.user.list`
+
+Evidence version: CLI mammoth-cli 1.1.11; mammoth-io 0.7.1. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -148,7 +148,7 @@ Expected success: `DashboardCreateBlankResult` in the standard JSON envelope; mu
 
 Run: `mammoth dashboard data draft`. Exact input fields: `mammoth schema get dashboard.data.draft --output json --no-input`.
 
-Example: `mammoth dashboard data draft 123 --input '{"sql": "SELECT region, SUM(revenue) FROM data GROUP BY region"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard data draft 123 --input '{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardDataDraftResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -156,7 +156,7 @@ Expected success: `DashboardDataDraftResult` in the standard JSON envelope; muta
 
 Run: `mammoth dashboard data published`. Exact input fields: `mammoth schema get dashboard.data.published --output json --no-input`.
 
-Example: `mammoth dashboard data published 123 --input '{"sql": "SELECT region, SUM(revenue) FROM data GROUP BY region"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard data published 123 --input '{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardDataPublishedResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -460,7 +460,7 @@ Expected success: `DashboardQaSettingsSetResult` in the standard JSON envelope;
 
 Run: `mammoth dashboard query`. Exact input fields: `mammoth schema get dashboard.query --output json --no-input`.
 
-Example: `mammoth dashboard query 123 --input '{"body": {"params": {"descriptor": {}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard query 123 --input '{"body": {"params": {"descriptor": {"kind": "scalar", "agg": "count"}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardQueryResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -788,7 +788,7 @@ Expected success: `DashboardTrashResult` in the standard JSON envelope; mutation
 
 Run: `mammoth dashboard update`. Exact input fields: `mammoth schema get dashboard.update --output json --no-input`.
 
-Example: `mammoth dashboard update 123 --input '{"patch": [{"op": "add", "path": "intent", "value": "sample"}]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard update 123 --input '{"patch": [{"op": "replace", "path": "title", "value": "Renamed dashboard"}]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardUpdateResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `returns_job`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -32,3 +32,28 @@ mammoth schema find "dashboard" --output json --no-input
 Page/widget schemas vary by release. Read each schema, use returned IDs, and
 verify dashboard source plus draft/published data after every mutation. A
 creation response alone is not proof of a usable published view.
+
+## Canvas, widget data and PDF
+
+Never save an invented canvas. Read it, change it, write it back:
+
+```bash
+mammoth dashboard canvas get DASHBOARD_ID --output json --no-input   # data.canvas incl. style_tokens
+mammoth dashboard canvas save DASHBOARD_ID --input '{"body":{"params":{"canvas":CANVAS_FROM_GET}}}' --output json --no-input
+```
+
+`canvas save` with `{"canvas": {}}` fails (`dataset` and other fields are
+required); the object returned by `canvas get` is the only known-good shape.
+Widget ids for `dashboard data draft` / `dashboard data published` come from
+that canvas: `--input '{"widget_id": "WIDGET_UUID"}'` (optional
+`global_filters` / `drilldown_filters` objects). `dashboard query` needs a
+descriptor with a `kind` (`scalar`, `group`, `rate`, `detail`, `options`,
+`range`); `{"kind":"scalar","agg":"count"}` is the smallest that runs.
+
+`dashboard pdf export` and `dashboard video export` cannot be completed from
+the CLI: the backend requires the browser-hydrated `DashboardData` map
+(pre-rendered widget results) in `params.data` and refuses to rebuild it. Report
+this as a known limitation instead of retrying with `{}`. `dashboard create`
+(legacy engine) is retired on release (HTTP 409 `4DASH012`); use
+`create-blank` or `v3 generate`.
+

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -16,6 +16,10 @@ mammoth view list DATASET_ID --project PROJECT_ID --output json --no-input
 mammoth view get VIEW_ID --project PROJECT_ID --output json --no-input
 ```
 
+`file upload` takes the local path as its positional argument; there is no
+`--source`/`--file` option. `dataset delete` is asynchronous: re-read
+`dataset list` (the id disappears once the job completes) before reporting.
+
 Use display names from the exact view schema. For settings, folders and other
 families, use `schema find`/`schema get` first, then read back the exact parent
 and resource IDs. For example:

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -19,7 +19,21 @@ parent from `view list DATASET_ID` (you already know it after upload) or
 
 Prefer typed operations such as convert-type, fill-missing, replace, join,
 lookup, filter and math only when the live schema
-lists them. For each operation, a successful result should contain a returned
+lists them. Pick the operation by what it does, not by its name:
+
+- `fill-missing` copies the previous/next row's value into blanks
+  (`direction` = `LAST_VALUE` forward-fill or `FIRST_VALUE`). It cannot write a
+  literal. To fill blanks with a constant (for example `0`), use `set-values`
+  on the existing column with an `IS_EMPTY` condition:
+
+```bash
+mammoth view transform set-values VIEW_ID --project PROJECT_ID \
+  --input '{"dataset_id":DATASET_ID,"existing_column":"revenue","values":[{"value":0}],"condition":{"column":"revenue","operator":"IS_EMPTY"}}' \
+  --output json --no-input
+```
+
+- `filter` keeps matching rows by default (`filter_type: "SHOW"`); to drop
+  rows, say so: `{"condition":{"column":"units","operator":"LT","value":0},"filter_type":"REMOVE"}`. For each operation, a successful result should contain a returned
 task/job reference or updated view envelope; then verify with `view task list`,
 `view task get`, `view pipeline items`, or preview according to its schema.
 

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -50,7 +50,9 @@ or secrets in an argument, prompt, transcript, or checkpoint.
 4. Discover instead of guessing. Run `mammoth schema list/find/get --output
    json --no-input` for local CLI routes; `mammoth capability list --output
    json --no-input` is an API-binding inventory and can omit typed/local
-   routes. Then resolve workspace/project/dataset/view
+   routes. Check [capabilities](capabilities.md) for whether a route is
+   proven, not supported, or untried on release before building a plan on
+   it. Then resolve workspace/project/dataset/view
    parents with reads. Use display names returned by the exact view schema.
 5. Translate the business intent into a plan the agent chooses. Submit only
    supported operations with explicit `--project` (and other returned parents),

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/commands/dashboard.py

@@ -365,24 +365,52 @@ def dashboard_analytics(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _widget_data_kwargs(invocation: Invocation) -> dict[str, Any]:
+    """Bind the ``WidgetDataSpec`` fields the draft/published data routes take.
+
+    ``widget_id`` (the widget UUID) is required; ``global_filters`` and
+    ``drilldown_filters`` are optional ``{column: value}`` objects.
+    """
+    document = _bound_document(invocation)
+    widget_id = _require_field(document, "widget_id")
+    if not isinstance(widget_id, str) or not widget_id.strip():
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="The 'widget_id' input field must be a non-empty widget UUID string.",
+            exit_status=EXIT_USAGE,
+            hint="Read widget ids from 'mammoth dashboard canvas get DASHBOARD_ID'.",
+        )
+    kwargs: dict[str, Any] = {"widget_id": widget_id}
+    for name in ("global_filters", "drilldown_filters"):
+        if name not in document:
+            continue
+        value = document[name]
+        if not isinstance(value, dict):
+            raise CliError(
+                code=CODE_INVALID_ARGUMENT,
+                message=f"The '{name}' input field must be an object of column -> value.",
+                exit_status=EXIT_USAGE,
+            )
+        kwargs[name] = value
+    return kwargs
+
+
 def dashboard_data_draft(invocation: Invocation) -> HandlerResult:
-    """Run a SQL query against a dashboard's draft data. ``sql`` comes from ``--input``."""
+    """Read one widget's rows from a dashboard's draft state. Fields come from ``--input``."""
     dashboard_id = _require_int_positional(invocation, "dashboard id")
-    document = _bound_document(invocation)
-    sql = _require_field(document, "sql")
+    kwargs = _widget_data_kwargs(invocation)
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, sql=sql)
+        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, **kwargs)
         data = _resolve_job(service, invocation, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
 def dashboard_data_published(invocation: Invocation) -> HandlerResult:
-    """Run a SQL query against a dashboard's published data. ``sql`` from ``--input``."""
+    """Read one widget's rows from a dashboard's published state. Fields from ``--input``."""
     dashboard_id = _require_int_positional(invocation, "dashboard id")
-    document = _bound_document(invocation)
-    sql = _require_field(document, "sql")
+    kwargs = _widget_data_kwargs(invocation)
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, sql=sql)
+        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, **kwargs)
         data = _resolve_job(service, invocation, data)
     return data, _meta(invocation, auth.workspace_id)
 
@@ -561,6 +589,10 @@ def dashboard_archive(invocation: Invocation) -> HandlerResult:
         data = service.call(
             _symbol(invocation), dashboard_id=dashboard_id, archived=document["archived"]
         )
+    if not isinstance(data, dict):
+        # The route declares no response body; give the committed state a
+        # stable object shape instead of a bare scalar.
+        data = {"dashboard_id": dashboard_id, "archived": document["archived"], "response": data}
     return data, _meta(invocation, auth.workspace_id)
 
 

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/output/normalize.py

@@ -14,6 +14,7 @@ import decimal
 import enum
 import ipaddress
 import math
+import re
 import uuid
 from collections.abc import Mapping
 from pathlib import Path
@@ -50,12 +51,33 @@ class _NormalizedJsonSchema(dict[str, Any]):
     """
 
 
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+# Plural ``*_tokens`` keys that still name credentials rather than design data.
+_CREDENTIAL_TOKEN_PREFIXES = ("access", "refresh", "auth", "api", "bearer", "session", "oauth")
+
+
 def _is_secret_key(key: str) -> bool:
-    lowered = key.lower()
+    # ``styleTokens`` and ``style_tokens`` must be judged the same way.
+    lowered = _CAMEL_BOUNDARY.sub("_", key).lower()
     # ``token_count`` is ordinary result metadata (for example an LLM usage
     # counter), not a credential.  Do not let the broad token guard erase it.
-    if lowered in {"token_count", "next_token", "continuation_token", "design_tokens"}:
+    if lowered in {
+        "token_count",
+        "next_token",
+        "continuation_token",
+        "page_token",
+        "design_tokens",
+    }:
         return False
+    if "token" in lowered and not any(
+        hint in lowered for hint in _SECRET_KEY_HINTS if hint != "token"
+    ):
+        # Credential tokens are singular (``token``, ``access_token``).  Plural
+        # ``tokens`` / ``style_tokens`` are dashboard design-system data, and
+        # erasing them breaks the canvas get -> save round-trip.
+        if lowered == "tokens" or lowered.endswith("_tokens"):
+            return lowered.startswith(_CREDENTIAL_TOKEN_PREFIXES)
+        return True
     return any(hint in lowered for hint in _SECRET_KEY_HINTS)
 
 
@@ -69,8 +91,7 @@ def _is_secret_value(value: Any) -> bool:
     """
     value_type = type(value)
     return value_type.__name__ in {"SecretStr", "SecretBytes"} or (
-        "secret" in value_type.__name__.lower()
-        and hasattr(value, "get_secret_value")
+        "secret" in value_type.__name__.lower() and hasattr(value, "get_secret_value")
     )
 
 

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/services/input_fields.py

@@ -145,6 +145,20 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     # Blank dashboard creation requires a typed params envelope. Keep the
     # generated destructive example runnable with the explicit approval flag.
     "dashboard.create-blank": {"params": {"dataview_id": 1}},
+    # The draft/published data routes take a WidgetDataSpec keyed by the
+    # widget UUID (read it from ``dashboard canvas get``), not a SQL string.
+    "dashboard.data.draft": {"widget_id": "550e8400-e29b-41d4-a716-446655440000"},
+    "dashboard.data.published": {"widget_id": "550e8400-e29b-41d4-a716-446655440000"},
+    # ``descriptor`` is a baked/1 QueryDescriptor discriminated by ``kind``
+    # (group | scalar | rate | detail | options | range); an empty object is
+    # rejected. A scalar row count runs against any dashboard.
+    "dashboard.query": {"body": {"params": {"descriptor": {"kind": "scalar", "agg": "count"}}}},
+    # ``path`` is a bare field name (title | intent | theme | pages | filters),
+    # not a JSON pointer, and an ``intent`` value must be at least 10 chars; a
+    # title rename is the smallest patch that runs.
+    "dashboard.update": {
+        "patch": [{"op": "replace", "path": "title", "value": "Renamed dashboard"}]
+    },
 }
 
 

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/services/mapping.py

@@ -321,6 +321,37 @@ def map_sdk_exception(
             details=dict(getattr(exc, "details", {}) or {}),
         )
 
+    errors = getattr(exc, "errors", None)
+    if type(exc).__name__ == "ValidationError" and callable(errors):
+        # A pydantic validation failure: say which fields, not just the class
+        # name, or the operator cannot tell what was wrong with the call.
+        try:
+            raw_errors = errors(include_url=False, include_input=False)
+        except TypeError:
+            raw_errors = errors()
+        summary = [
+            {
+                "loc": ".".join(str(part) for part in item.get("loc", ())),
+                "type": item.get("type"),
+                "msg": item.get("msg"),
+            }
+            for item in list(raw_errors)[:10]
+        ]
+        return CliError(
+            code=CODE_API_ERROR,
+            message=(
+                f"The SDK could not validate {getattr(exc, 'title', 'the payload')} "
+                "against its model."
+            ),
+            exit_status=EXIT_API,
+            hint="Compare the listed fields with 'mammoth schema get COMMAND_ID'.",
+            details={
+                "exception_type": "ValidationError",
+                "model": getattr(exc, "title", None),
+                "validation_errors": summary,
+            },
+        )
+
     return CliError(
         code=CODE_API_ERROR,
         message="The Mammoth operation failed unexpectedly.",

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/mammoth_cli/services/positionals.py

@@ -157,6 +157,14 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
     "dashboard.templates.use": (
         PositionalSpec(name="slug", type=str, required=True, help="Template slug."),
     ),
+    # The widget UUID is a WidgetDataSpec field, read from ``--input`` with the
+    # optional filters; only the dashboard is addressed positionally.
+    "dashboard.data.draft": (
+        PositionalSpec(name="dashboard_id", type=int, required=True, help="ID of the dashboard."),
+    ),
+    "dashboard.data.published": (
+        PositionalSpec(name="dashboard_id", type=int, required=True, help="ID of the dashboard."),
+    ),
     "dashboard.tags.merge": (
         PositionalSpec(name="tag_id", type=int, required=True, help="ID of the source tag."),
     ),

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.13"
+version = "2.0.14"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.7.5,<0.8)",
+    "mammoth-io (>=0.7.6,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.0.13 → mammoth_cli-2.0.14}/spec/manifests/commands/dashboard.yaml

@@ -738,8 +738,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth dashboard data draft DASHBOARD_ID --help
-  agent_example: 'mammoth dashboard data draft 123 --input ''{"sql": "SELECT region, SUM(revenue) FROM
-    data GROUP BY region"}'' --output json --no-input'
+  agent_example: 'mammoth dashboard data draft 123 --input ''{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}''
+    --output json --no-input'
   unit_tests:
   - UT-DASHBOARD-DATA-DRAFT
   contract_tests:
@@ -779,8 +779,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth dashboard data published DASHBOARD_ID --help
-  agent_example: 'mammoth dashboard data published 123 --input ''{"sql": "SELECT region, SUM(revenue)
-    FROM data GROUP BY region"}'' --output json --no-input'
+  agent_example: 'mammoth dashboard data published 123 --input ''{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}''
+    --output json --no-input'
   unit_tests:
   - UT-DASHBOARD-DATA-PUBLISHED
   contract_tests:
@@ -1398,7 +1398,9 @@ commands:
   - CT-DASHBOARD-PDF-EXPORT-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: Backend requires params.data to be the browser-hydrated DashboardData map
+    (pre-rendered widget results); the server stores only query descriptors and cannot rebuild
+    it, so a PDF cannot be produced from the CLI alone.
   reviewed_by: primary
 - command_id: dashboard.published-data-by-url
   command_path: dashboard published-data-by-url
@@ -2415,8 +2417,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth dashboard query DASHBOARD_ID --help
-  agent_example: 'mammoth dashboard query 123 --input ''{"body": {"params": {"descriptor": {}}}}'' --output
-    json --no-input'
+  agent_example: 'mammoth dashboard query 123 --input ''{"body": {"params": {"descriptor": {"kind": "scalar",
+    "agg": "count"}}}}'' --output json --no-input'
   unit_tests:
   - UT-DASHBOARD-QUERY
   contract_tests:
@@ -3999,8 +4001,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth dashboard update DASHBOARD_ID --help
-  agent_example: 'mammoth dashboard update 123 --input ''{"patch": [{"op": "add", "path": "intent", "value":
-    "sample"}]}'' --output json --no-input'
+  agent_example: 'mammoth dashboard update 123 --input ''{"patch": [{"op": "replace", "path": "title", "value":
+    "Renamed dashboard"}]}'' --output json --no-input'
   unit_tests:
   - UT-DASHBOARD-UPDATE
   contract_tests: