mammoth-cli 2.0.16__tar.gz → 2.0.17__tar.gz

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.16
+Version: 2.0.17
 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.8
+Requires-Dist: mammoth-io<0.8,>=0.7.9
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/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.16"
+__version__ = "2.0.17"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -38,11 +38,18 @@ the result.
 
 ## Working rules
 
+- Every command takes its resource ids as positionals, its request fields as
+  one `--input` JSON document, plus the shared global options (`--project`,
+  `--profile`, `--output`, `--no-input`, `--yes`, `--confirm`, timeouts).
+  There are no per-field flags: `project create NAME`, not `project create
+  --name NAME`. `schema get COMMAND_ID` lists the positionals and input fields.
 - Resolve workspace/project/dataset/view parents from reads; pass observed IDs
   and `--project`. A dataset does not select a default view. Every `view`
   command that changes, exports, or deletes data requires the exact parent
-  `DATASET_ID` (trailing positional or `dataset_id` input field); only reads
-  may omit it and discover the parent. Get it from `mammoth view get VIEW_ID`.
+  `DATASET_ID`: `view transform *` and `view draft *` take it as the
+  `dataset_id` input field, every other `view` command as the trailing
+  positional after `VIEW_ID`; only reads may omit it and discover the parent.
+  Get it from `mammoth view get VIEW_ID`.
 - Uploads and dataset creation return a **dataset** id. Transforms, joins,
   exports, and previews need a **view** id: run `view list DATASET_ID
   --project PROJECT_ID` to get it. See
@@ -51,6 +58,13 @@ the result.
   never backend aliases.
 - Inspect the result after a mutation. A timeout, exit 7, or interruption does
   not prove it failed. Reconcile an `outcome_unknown` before replaying it.
+- A success envelope is not proof the mutation did what you meant. After a
+  row-scoped change (set-values, filter, replace, join, fill) read rows back
+  with `view data get VIEW_ID DATASET_ID` and check both rows the condition
+  should have touched and rows it should not have. A uniform result (every
+  amount 0, every region "Unknown", most join rows unmatched) is a signal
+  that the previous step went wrong, not a fact about the source data: stop
+  and re-inspect that step before building anything on it.
 - Keep secrets out of argv, task notes, checkpoints, logs, and responses.
 - Preserve requested deliverables. Cleanup is exact-ID authorized and never means delete-all-owned-resources.
 
@@ -64,7 +78,10 @@ the result.
   or [recovery](references/recovery.md)
 - **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)
+- **A known command family or exact command:** [command catalog](references/command-index.md),
+  then check the same command in [capabilities](references/capabilities.md)
+  before composing input from its example (the catalog lists retired and
+  blocked routes with the same wording as working ones)
 - **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

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-455 API operations have a CLI command. 225 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.
+455 API operations have a CLI command. 227 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:
 
@@ -18,7 +18,7 @@ The typed `view transform *` commands all submit through `view.task.add`; its ro
 | Family | Commands | Verified | Not supported | Untried |
 |---|---|---|---|---|
 | `dashboard` | 104 | 81 | 2 | 21 |
-| `view` | 62 | 50 | 0 | 12 |
+| `view` | 62 | 52 | 0 | 10 |
 | `support` | 45 | 9 | 0 | 36 |
 | `billing` | 23 | 4 | 0 | 19 |
 | `connector` | 22 | 2 | 0 | 20 |
@@ -237,21 +237,19 @@ Verified: `user.get`, `user.preference.get`, `user.preference.update`
 
 ## `view`
 
-Verified: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-data`, `view.ai.profile`, `view.bulk-delete`, `view.checkpoint.create`, `view.checkpoint.delete`, `view.checkpoint.list`, `view.conditional-format.list`, `view.conditional-format.update`, `view.create`, `view.data-check.create`, `view.data-check.delete`, `view.data-check.get`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.delete`, `view.derivative.create`, `view.derivative.delete`, `view.derivative.list`, `view.derivative.update`, `view.draft.command`, `view.export.delete`, `view.export.get`, `view.export.list`, `view.export.publish-db`, `view.export.update`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.edit`, `view.pipeline.get`, `view.pipeline.items`, `view.pipeline.rerun`, `view.preview`, `view.restore`, `view.task.add`, `view.task.delete`, `view.task.get`, `view.task.list`, `view.task.update`, `view.trash`, `view.version.apply`, `view.version.delete`, `view.version.get`, `view.version.list`, `view.version.update`
+Verified: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-data`, `view.ai.profile`, `view.bulk-delete`, `view.checkpoint.create`, `view.checkpoint.delete`, `view.checkpoint.list`, `view.conditional-format.create`, `view.conditional-format.delete-all`, `view.conditional-format.list`, `view.conditional-format.update`, `view.create`, `view.data-check.create`, `view.data-check.delete`, `view.data-check.get`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.delete`, `view.derivative.create`, `view.derivative.delete`, `view.derivative.list`, `view.derivative.update`, `view.draft.command`, `view.export.delete`, `view.export.get`, `view.export.list`, `view.export.publish-db`, `view.export.update`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.edit`, `view.pipeline.get`, `view.pipeline.items`, `view.pipeline.rerun`, `view.preview`, `view.restore`, `view.task.add`, `view.task.delete`, `view.task.get`, `view.task.list`, `view.task.update`, `view.trash`, `view.version.apply`, `view.version.delete`, `view.version.get`, `view.version.list`, `view.version.update`
 
 | Command | State | Note |
 |---|---|---|
 | `view.ai.generation-info` | observed blocker | backend: GET /workspaces/4/projects/24/datasets/54/dataviews/76/data/generate -> HTTP 400 5GENR011 NOT_IMPLEMENTED 'Not implemented', request_id:null |
 | `view.checkpoint.get` | observed blocker | backend: GET /workspaces/4/projects/24/datasets/54/dataviews/76/pipeline/checkpoints/2 -> HTTP 500, empty response_body:{}, request_id:null, backend code: none surfaced (generic ap |
 | `view.checkpoint.update` | observed blocker | backend_error: CLI-side fix (payload now carries value:null as required) held: the correctly-shaped request was dispatched and the backend returned HTTP 500 (not a CLI-side crash): |
-| `view.conditional-format.create` | observed blocker | cli_error: Skill doc (view.md) claims this route is 'fail-closed and must not dispatch a request' (BLOCKED B09 DATAVIEW_INPUT_UNTYPED) -- but live it DOES dispatch: HTTP 400 4GENR0 |
 | `view.data-check.update` | observed blocker | backend: PATCH .../pipeline/data-checks/3 -> HTTP 500, empty response_body, request_id:null, code:outcome_unknown |
 | `view.derivative.data` | observed blocker | backend: POST .../derivatives/4/data -> HTTP 500, empty response_body, request_id:null, code:outcome_unknown |
 | `view.export.create` | observed blocker | backend: CLI accepts the request (exit 0, job 358 accepted on POST /dataviews/76/actions), but job get 358 -> status:error, response:{"error":{"message":"'destination'"}} (a raw Py |
 | `view.exportable-config.apply` | observed blocker | cli_error: Schema's own runnable_example (config:{tasks:[]}) fails: job_failed, response:{reason:(quote)dependencies(quote)} -- a raw Python KeyError, not a structured validation m |
-| `view.conditional-format.delete-all` | CLI defect fixed, untried since | 2.0.16 (the handler now forwards rule_id from --input (2.0.15 accepted the field but dropped it before the SDK call)) |
+| `view.task.preview` | observed blocker | backend_error: Fix held: the COPY task_spec is accepted and a task_preview job (406) is created; the job then fails backend-side with 'Object of type datetime is not JSON serializa |
 | `view.export.publish-db-update` | CLI defect fixed, untried since | 2.0.16 (example value is the documented {"odbc_type": "postgres"} object (a bare string is rejected)) |
-| `view.task.preview` | CLI defect fixed, untried since | 2.0.16 (example now uses the backend COPY param-template shape: list of {SOURCE, AS{COLUMN,TYPE,INTERNAL_NAME}}, VERSION 2 |
 
 ## `webhook`
 
@@ -267,4 +265,4 @@ Verified: `workflow.graph`, `workflow.list`, `workflow.workspace-datasets`, `wor
 
 Verified: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.segment.update`, `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.
+Evidence collected on CLI releases 1.1.5 through 2.0.17; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row verified on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -92,7 +92,7 @@ Expected success: `ViewCheckpointUpdateResult` in the standard JSON envelope; mu
 
 Run: `mammoth view conditional-format create`. Exact input fields: `mammoth schema get view.conditional-format.create --output json --no-input`.
 
-Example: `mammoth view conditional-format create 123 123 --input '{"rule": {"sample_key": "Status"}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view conditional-format create 123 123 --input '{"rule": {"cf_type": "RULE", "payload": {"FORMAT": {"name": "Flag open orders", "color": "red", "applies_to": "row", "column_ids": "[]"}, "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewConditionalFormatCreateResult` 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.
 
@@ -100,7 +100,7 @@ Expected success: `ViewConditionalFormatCreateResult` in the standard JSON envel
 
 Run: `mammoth view conditional-format delete-all`. Exact input fields: `mammoth schema get view.conditional-format.delete-all --output json --no-input`.
 
-Example: `mammoth view conditional-format delete-all 123 123 --input '{"rule_id": "rule-1"}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth view conditional-format delete-all 123 123 --input '{"rule_id": "bca0ff33bd6f8ed1"}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
 
 Expected success: `ViewConditionalFormatDeleteAllResult` in the standard JSON envelope; mutation `destructive`, confirmation `prompt_or_yes`, 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.
 
@@ -668,7 +668,7 @@ Expected success: `ViewTransformAddColumnResult` in the standard JSON envelope;
 
 Run: `mammoth view transform add-sql`. Exact input fields: `mammoth schema get view.transform.add-sql --output json --no-input`.
 
-Example: `mammoth view transform add-sql 123 --input '{"query": "SELECT region, SUM(revenue) FROM data GROUP BY region", "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view transform add-sql 123 --input '{"query": "SELECT region, SUM(revenue) AS revenue FROM \"view:123\" GROUP BY region", "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewTransformAddSqlResult` in the standard JSON envelope; mutation `reversible_pipeline`, 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.
 

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -6,9 +6,11 @@ id instead. Run `view list DATASET_ID --project PROJECT_ID` to get it. Do not
 dig through `dataset get` and its `dependencies` field for a view id; `view
 list` is the supported route.
 
-Discover exact contracts, then upload and read back explicit parents:
+Discover exact contracts, then upload and read back explicit parents. A new
+project takes its name as the positional argument:
 
 ```bash
+mammoth project create 'PROJECT NAME' --output json --no-input
 mammoth schema get file.upload --output json --no-input
 mammoth file upload ./SOURCE.csv --project PROJECT_ID --output json --no-input
 mammoth dataset list --project PROJECT_ID --output json --no-input
@@ -17,7 +19,9 @@ 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
+`--source`/`--file` option. Its result carries the status the platform holds
+for each created dataset: `ready`, or `need_action` with a `next_command`, in
+which case follow [need-action](need-action.md) before looking for a view. `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

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -30,8 +30,14 @@ lists them. Pick the operation by what it does, not by its name:
 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
+mammoth view data get VIEW_ID DATASET_ID --project PROJECT_ID --output json --no-input
 ```
 
+Then confirm from the read-back that blank rows are now `0` and non-blank
+rows kept their values. If non-matching rows changed too, the condition was
+not applied: stop, do not build joins or summaries on this view, and report
+it.
+
 - `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`,
@@ -64,6 +70,44 @@ mammoth schema get view.transform.join --output json --no-input
 mammoth view transform join VIEW_ID --project PROJECT_ID --input INPUT_JSON --output json --no-input
 ```
 
+## Aggregate or summarise
+
+For a grouped summary (totals per region, counts per status) use the typed
+`pivot` when the live schema lists it, or a SQL task. A SQL task must be one
+SELECT that names the view as the quoted table `"view:VIEW_ID"` (or its quoted
+display name) with display-name columns; unquoted or placeholder table names
+(`data`, `__TABLE__`) are rejected with "table name ... not found" or "only
+select queries allowed". The result replaces the view's columns, so run it on
+a copy (`view create` with `clone_from`) or as the last step:
+
+```bash
+mammoth schema get view.transform.pivot --output json --no-input
+mammoth view transform add-sql VIEW_ID --project PROJECT_ID \
+  --input '{"dataset_id":DATASET_ID,"query":"SELECT region, SUM(amount) AS total_amount, COUNT(*) AS order_count FROM \"view:VIEW_ID\" GROUP BY region"}' \
+  --output json --no-input
+mammoth view data get VIEW_ID DATASET_ID --project PROJECT_ID --output json --no-input
+```
+
+Read the data back after every value-changing step (`view data get`, or
+`view preview`); a task that executed is not proof it changed the rows you
+meant, and a join that matched nothing shows nulls, not a filled default. A
+join that leaves most rows unmatched is not evidence about the source data
+until you have sampled the key column on both sides (`view data get` on
+each view) and confirmed an earlier step did not rewrite the key or the
+values you are summing.
+
+## How to look at your data
+
+- Schema and types: `view get VIEW_ID` (falls back to discovery) or
+  `dataset get DATASET_ID`; the column list with display names is what every
+  transform input must use.
+- Rows and values: `view data get VIEW_ID DATASET_ID` (paged) or
+  `view preview VIEW_ID` for a sample; use these after every value-changing
+  step and before reporting any number.
+- What actually ran: `view task list VIEW_ID`, `view task get VIEW_ID TASK_ID`,
+  `view pipeline get VIEW_ID` (state, auto_run, executing task).
+- Async completion: `job get JOB_ID` / `job wait JOB_ID`.
+
 Reject malformed fields with the structured error envelope and stop rather than
 guessing names. Verify exact display names, join multiplicity, math values and
 remote task/pipeline readback. Draft submit is not proof all tasks persisted:

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/commands/file.py

@@ -11,6 +11,7 @@ SDK method named by the command's reviewed manifest ``sdk_symbol``.
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
 from mammoth_cli.errors.envelope import (
@@ -214,25 +215,64 @@ def file_upload(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    # The SDK waits for the upload to finish and returns the created dataset
-    # id(s) as a bare int/list. Wrap it in a labeled result so the output reads
-    # as a finished dataset rather than an anonymous number. When the caller
-    # opts out of waiting (``wait_for_completion: false``) the bare job id is
-    # returned unchanged.
-    if not document.get("wait_for_completion", True):
-        return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
-    return _upload_result(data), _meta(invocation, auth.workspace_id, resolved_project(invocation))
-
-
-def _upload_result(value: Any) -> dict[str, Any]:
-    """Shape the SDK upload return (int | list[int] | None) into a labeled result."""
+        # The SDK waits for the upload job and returns the created dataset
+        # id(s) as a bare int/list. When the caller opts out of waiting
+        # (``wait_for_completion: false``) the bare job id is returned unchanged.
+        if not document.get("wait_for_completion", True):
+            return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+        # A finished upload job does not mean a usable dataset: a CSV with an
+        # ambiguous date column lands in ``need_action`` with no view. Report
+        # the status the platform holds for each dataset, not an assumed one.
+        result = _upload_result(data, lambda dataset_id: _dataset_status(service, dataset_id))
+    return result, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+_DATASET_GET_SYMBOL = "mammoth.api.datasets.DatasetsAPI.get"
+
+
+def _dataset_status(service: Any, dataset_id: int) -> tuple[str, dict[str, Any] | None]:
+    """Read ``(status, status_info)`` for one dataset; ``unknown`` if the read fails."""
+    try:
+        response = service.call(_DATASET_GET_SYMBOL, dataset_id=dataset_id)
+    except CliError:
+        return "unknown", None
+    dataset = response.get("dataset", response) if isinstance(response, dict) else {}
+    status = dataset.get("status") if isinstance(dataset, dict) else None
+    status_info = dataset.get("status_info") if isinstance(dataset, dict) else None
+    return (
+        status if isinstance(status, str) else "unknown",
+        status_info if isinstance(status_info, dict) else None,
+    )
+
+
+def _upload_result(
+    value: Any, read_status: Callable[[int], tuple[str, dict[str, Any] | None]]
+) -> dict[str, Any]:
+    """Shape the SDK upload return (int | list[int] | None) into a labeled result.
+
+    ``status`` is ``ready`` only when every created dataset reads back as
+    ``ready``; otherwise it is the first non-ready status so a caller that
+    checks one field sees the dataset that still needs work. ``datasets``
+    carries the per-dataset status, and a ``need_action`` dataset also gets
+    the recovery route so the caller does not have to know the recipe.
+    """
     if isinstance(value, list):
         ids = [int(v) for v in value]
     elif isinstance(value, int):
         ids = [value]
     else:
         ids = []
-    result: dict[str, Any] = {"status": "ready", "dataset_ids": ids}
+    datasets: list[dict[str, Any]] = []
+    for dataset_id in ids:
+        status, status_info = read_status(dataset_id)
+        entry: dict[str, Any] = {"id": dataset_id, "status": status}
+        if status_info:
+            entry["status_info"] = status_info
+        if status == "need_action":
+            entry["next_command"] = f"mammoth dataset file-settings get {dataset_id}"
+        datasets.append(entry)
+    overall = next((d["status"] for d in datasets if d["status"] != "ready"), "ready")
+    result: dict[str, Any] = {"status": overall, "dataset_ids": ids, "datasets": datasets}
     if len(ids) == 1:
         result["dataset_id"] = ids[0]
     return result

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/runtime/strict.py

@@ -60,6 +60,36 @@ CODE_INVALID_INPUT_FIELD_TYPE = "invalid_input_field_type"
 _TRUE_STRINGS = frozenset({"true", "1", "yes", "y", "on"})
 _FALSE_STRINGS = frozenset({"false", "0", "no", "n", "off"})
 
+def _unknown_option_hint(command_id: str, token: str) -> tuple[str, dict[str, Any]]:
+    """Name the accepted form when an unknown ``--option`` matches a real field.
+
+    Generic leaves take no per-field options, so ``--name`` on ``project
+    create`` is a guess at the positional ``name`` and ``--dataset-id`` on a
+    view command is a guess at the ``dataset_id`` input field. Saying which
+    lets a caller fix the call without a schema round-trip.
+    """
+    guessed = token.lstrip(_OPTION_PREFIX).split("=", 1)[0].replace("-", "_")
+    command = command_id.replace(".", " ")
+    if guessed:
+        for position, spec in enumerate(resolve_positionals(command_id)):
+            if spec.name == guessed:
+                return (
+                    f"'{guessed}' is positional argument {position + 1} of '{command}', "
+                    f"not an option: mammoth {command} {guessed.upper()}.",
+                    {"positional": guessed},
+                )
+        contract = resolve_command_contract(command_id)
+        if contract is not None and any(
+            field.name == guessed for field in contract.accepted_fields
+        ):
+            return (
+                f"'{guessed}' is an --input field of '{command}', not an option: "
+                f"pass --input '{{\"{guessed}\": VALUE}}' after the positional arguments.",
+                {"input_field": guessed},
+            )
+    return "Check the command schema with 'mammoth schema get'.", {}
+
+
 def validate_extra_args(command_id: str, extra_args: Iterable[str]) -> None:
     """Reject unrecognized options and surplus positional tokens.
 
@@ -79,12 +109,13 @@ def validate_extra_args(command_id: str, extra_args: Iterable[str]) -> None:
     tokens = list(extra_args)
     for token in tokens:
         if token.startswith(_OPTION_PREFIX) and token != _OPTION_PREFIX:
+            hint, hint_details = _unknown_option_hint(command_id, token)
             raise CliError(
                 code=CODE_UNKNOWN_OPTION,
                 message=f"Unknown option '{token}' for '{command_id.replace('.', ' ')}'.",
                 exit_status=EXIT_USAGE,
-                hint="Check the command schema with 'mammoth schema get'.",
-                details={"option": token},
+                hint=hint,
+                details={"option": token, **hint_details},
             )
 
     max_positionals = len(resolve_positionals(command_id))

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/services/input_fields.py

@@ -173,7 +173,24 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     },
     "view.ai.profile": {"dataset_id": 456, "action": "insights"},
     "connector.query.generate": {"query": "Total sales for January"},
-    "view.conditional-format.delete-all": {"rule_id": "rule-1"},
+    # HighlightEntry: cf_type + payload{FORMAT, CONDITION keyed by internal
+    # column name}; the create response and ``conditional-format list`` carry
+    # the generated rule_id that delete-all needs.
+    "view.conditional-format.create": {
+        "rule": {
+            "cf_type": "RULE",
+            "payload": {
+                "FORMAT": {
+                    "name": "Flag open orders",
+                    "color": "red",
+                    "applies_to": "row",
+                    "column_ids": "[]",
+                },
+                "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]},
+            },
+        }
+    },
+    "view.conditional-format.delete-all": {"rule_id": "bca0ff33bd6f8ed1"},
     "dataset.bulk-delete": {"dataset_ids": [456, 457]},
     "folder.move": {"resource_ids": [8024], "target_folder_resource_id": "root"},
     "project.update": {"name": "Renamed project"},
@@ -217,6 +234,11 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
             }
         ]
     },
+    # The SQL task reads the view as the quoted table "view:<id>" (or its
+    # quoted display name); placeholder names such as ``data`` are rejected.
+    "view.transform.add-sql": {
+        "query": 'SELECT region, SUM(revenue) AS revenue FROM "view:123" GROUP BY region'
+    },
     "view.checkpoint.update": {
         "body": {"patches": [{"op": "command", "path": "approve", "value": None}]},
     },

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/mammoth_cli/services/sdk_service.py

@@ -129,6 +129,19 @@ class SdkMammothService:
                 hint="Check the command schema with 'mammoth schema get'.",
                 details={"reason": str(exc)},
             ) from exc
+        except ValueError as exc:
+            # ``ViewsResource.get`` and the view-scoped API methods reach the
+            # same project-wide parent discovery as ``call_view``; a miss must
+            # read as not_found here too, not "operation failed unexpectedly".
+            miss = self._discovery_miss_error(exc, kwargs.get("view_id", kwargs.get("dataview_id")))
+            if miss is not None:
+                raise miss from exc
+            raise map_sdk_exception(
+                exc,
+                profile=self._profile,
+                project_id=self._project_id,
+                workspace_id=self._workspace_id,
+            ) from exc
         except Exception as exc:
             raise map_sdk_exception(
                 exc,
@@ -137,6 +150,34 @@ class SdkMammothService:
                 workspace_id=self._workspace_id,
             ) from exc
 
+    def _discovery_miss_error(self, exc: ValueError, view_id: Any) -> CliError | None:
+        """Map the SDK's bare "not found in any dataset" ValueError to not_found.
+
+        Returns None when ``exc`` is some other ValueError so the caller can
+        apply the generic mapping.
+        """
+        if "not found in any dataset" not in str(exc):
+            return None
+        project = self._client.project_id
+        return CliError(
+            code=CODE_RESOURCE_NOT_FOUND,
+            message=(
+                f"View {view_id} was not found in any dataset of project {project}; "
+                "parent discovery walked every visible dataset and folder."
+            ),
+            exit_status=EXIT_NOT_FOUND,
+            hint=(
+                "Check the project (views live in exactly one project) and pass the "
+                "exact parent DATASET_ID from 'view list DATASET_ID' or a dataset "
+                "read; do not rely on discovery for large projects."
+            ),
+            details={"view_id": view_id, "project_id": project, "reason": str(exc)},
+            recovery_commands=[
+                f"mammoth dataset list --project {project} --output json --no-input",
+                "mammoth dataset find NAME_SUBSTRING --output json --no-input",
+            ],
+        )
+
     @staticmethod
     def _coerce_call_arguments(method: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
         """Coerce generic-``call`` kwargs to the method's annotated types.
@@ -233,27 +274,10 @@ class SdkMammothService:
             # The SDK's project-wide parent discovery reports a miss as a bare
             # ValueError. Name it, and hand back the reads that settle it,
             # instead of flattening it into "operation failed unexpectedly".
-            if "not found in any dataset" not in str(exc):
+            miss = self._discovery_miss_error(exc, view_id)
+            if miss is None:
                 raise map_sdk_exception(exc) from exc
-            project = self._client.project_id
-            raise CliError(
-                code=CODE_RESOURCE_NOT_FOUND,
-                message=(
-                    f"View {view_id} was not found in any dataset of project {project}; "
-                    "parent discovery walked every visible dataset and folder."
-                ),
-                exit_status=EXIT_NOT_FOUND,
-                hint=(
-                    "Check the project (views live in exactly one project) and pass the "
-                    "exact parent DATASET_ID from 'view list DATASET_ID' or a dataset "
-                    "read; do not rely on discovery for large projects."
-                ),
-                details={"view_id": view_id, "project_id": project, "reason": str(exc)},
-                recovery_commands=[
-                    f"mammoth dataset list --project {project} --output json --no-input",
-                    "mammoth dataset find NAME_SUBSTRING --output json --no-input",
-                ],
-            ) from exc
+            raise miss from exc
         except Exception as exc:
             raise map_sdk_exception(exc) from exc
         if method.startswith("_"):

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.16"
+version = "2.0.17"
 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.8,<0.8)",
+    "mammoth-io (>=0.7.9,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.0.16 → mammoth_cli-2.0.17}/spec/manifests/commands/view.yaml

@@ -546,8 +546,9 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view conditional-format create VIEW_ID --help
-  agent_example: 'mammoth view conditional-format create 123 123 --input ''{"rule": {"sample_key": "Status"}}''
-    --output json --no-input'
+  agent_example: 'mammoth view conditional-format create 123 123 --input ''{"rule": {"cf_type": "RULE",
+    "payload": {"FORMAT": {"name": "Flag open orders", "color": "red", "applies_to": "row", "column_ids":
+    "[]"}, "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]}}}}'' --output json --no-input'
   unit_tests:
   - UT-VIEW-CONDITIONAL-FORMAT-CREATE
   contract_tests:
@@ -597,8 +598,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view conditional-format delete-all VIEW_ID --help
-  agent_example: 'mammoth view conditional-format delete-all 123 123 --input ''{"rule_id": "rule-1"}'' --output
-    json --no-input'
+  agent_example: 'mammoth view conditional-format delete-all 123 123 --input ''{"rule_id": "bca0ff33bd6f8ed1"}''
+    --output json --no-input'
   unit_tests:
   - UT-VIEW-CONDITIONAL-FORMAT-DELETE-ALL
   contract_tests:
@@ -3699,7 +3700,8 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view transform add-sql VIEW_ID --help
-  agent_example: 'mammoth view transform add-sql 123 --input ''{"query": "SELECT region, SUM(revenue) FROM data GROUP BY region", "dataset_id": 456}'' --output json --no-input'
+  agent_example: 'mammoth view transform add-sql 123 --input ''{"query": "SELECT region, SUM(revenue) AS
+    revenue FROM \"view:123\" GROUP BY region", "dataset_id": 456}'' --output json --no-input'
   unit_tests:
   - UT-VIEW-TRANSFORM-ADD-SQL
   contract_tests: