mammoth-cli 2.2.96__tar.gz → 2.2.98__tar.gz

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.96
+Version: 2.2.98
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -19,7 +19,7 @@ Requires-Python: <3.15,>=3.12
 Requires-Dist: certifi>=2026.10.19
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.49
+Requires-Dist: mammoth-io<0.9,>=0.8.50
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/app.py

@@ -1209,6 +1209,7 @@ def _execute(invocation: Invocation) -> None:
     from mammoth_cli.runtime.new_data import with_new_data_path
     from mammoth_cli.runtime.next_commands import with_next_commands
     from mammoth_cli.runtime.opens import with_opens
+    from mammoth_cli.runtime.reveal import REVEAL_COMMANDS, REVEAL_FLAG
     from mammoth_cli.runtime.strict import validate_extra_args
 
     if invocation.profile is None:
@@ -1219,6 +1220,12 @@ def _execute(invocation: Invocation) -> None:
             extra_args=[arg for arg in invocation.extra_args if arg != FULL_FLAG],
             full_output=True,
         )
+    if invocation.command_id in REVEAL_COMMANDS and REVEAL_FLAG in invocation.extra_args:
+        invocation = replace(
+            invocation,
+            extra_args=[arg for arg in invocation.extra_args if arg != REVEAL_FLAG],
+            reveal_secrets=True,
+        )
 
     def producer() -> tuple[Any, dict[str, Any]]:
         refuse_hand_crafted_write(invocation.command_id)
@@ -1508,6 +1515,13 @@ def _command_help(command_id: str, record: dict[str, Any] | None) -> str | None:
             "The result is compact: ids, checks, verify and a canvas summary. "
             f"Pass {FULL_FLAG} for the complete response."
         )
+    from mammoth_cli.runtime.reveal import REVEAL_COMMANDS, REVEAL_FLAG
+
+    if command_id in REVEAL_COMMANDS:
+        parts.append(
+            "The credential in the result is masked. Pass "
+            f"{REVEAL_FLAG} to print it; it is shown only once."
+        )
     return "\n\n".join(parts) or None
 
 
@@ -1546,7 +1560,14 @@ def _short_type(type_name: str) -> str:
     if "condition." in text:
         return "condition"
     # Drop each dotted module path but keep the brackets around it (``list[a.b.C]``).
-    return re.sub(r"(?:\w+\.)+(\w+)", r"\1", " | ".join(p.strip() for p in text.split("|")))[:60]
+    text = re.sub(r"(?:\w+\.)+(\w+)", r"\1", " | ".join(p.strip() for p in text.split("|")))
+    if len(text) <= _SHORT_TYPE_MAX:
+        return text
+    # Cut at a word, never inside one: a clipped value ('par) reads as a real one.
+    return text[: _SHORT_TYPE_MAX - 4].rsplit(" ", 1)[0] + " ..."
+
+
+_SHORT_TYPE_MAX = 60
 
 
 def _command_records() -> list[dict[str, Any]]:

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.2.96
+version: 2.2.98
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard-embed.md

@@ -36,7 +36,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth dashboard embed lifetime set`. Exact input fields: `mammoth schema get dashboard.embed.lifetime.set`.
 
-Example: `mammoth dashboard embed lifetime set 123 --input '{"token_ttl": 1}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth dashboard embed lifetime set 123 --input '{"token_ttl": 900}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `DashboardEmbedLifetimeSetResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -638,7 +638,7 @@ Run: `mammoth dashboard live-chart create`. Exact input fields: `mammoth schema
 
 Example: `mammoth dashboard live-chart create --input '{"body": {"params": {"view_id": 1, "figure": {}, "title": "Revenue report"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
-Result: `DashboardLiveChartCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+Result: `DashboardLiveChartCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `start_or_wait`.
 
 Status on release: untried; no live run recorded.
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -570,7 +570,7 @@ Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on
 
 Run: `mammoth view export download`. Exact input fields: `mammoth schema get view.export.download`.
 
-Example: `mammoth view export download 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view export download 123 --input '{"file_type": "xml"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `ViewExportDownloadResult`; mutation `benign_mutation`, confirmation `none`, wait policy `always_wait`.
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/dashboard.py

@@ -1,8 +1,9 @@
 """Handlers for the ``dashboard`` command family (workspace-scoped, no project).
 
 Dashboards are identified either by an integer ``dashboard_id`` (most commands)
-or by a share ``url`` slug (the ``*-by-url`` commands). None of the backing SDK
-signatures accept a ``project_id``, so handlers never resolve or forward one.
+or by a share ``url`` slug (the ``*-by-url`` commands). The few backing SDK
+methods that take a ``project_id`` (a new board's project) get an explicit
+``--project``; no other handler resolves or forwards one.
 Every handler dispatches through the generic
 :meth:`~mammoth_cli.services.protocol.MammothService.call` seam to the public
 SDK method named by the command's reviewed manifest ``sdk_symbol``.
@@ -15,6 +16,7 @@ from pathlib import Path
 from typing import Any, Literal, cast
 
 from mammoth.api import agents as agents_api
+from mammoth.api import dashboards as dashboards_api
 from mammoth.exceptions import MammothValidationError
 from pydantic import ValidationError
 
@@ -31,6 +33,7 @@ from mammoth_cli.errors.envelope import (
     CliError,
 )
 from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.output.normalize import Revealed, normalize
 from mammoth_cli.runtime import embedded, parents
 from mammoth_cli.runtime.confirm import (
     POLICY_CONFIRM_TARGET,
@@ -40,6 +43,7 @@ from mammoth_cli.runtime.confirm import (
     enforce_confirmation,
 )
 from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.reveal import REVEAL_COMMANDS
 from mammoth_cli.runtime.session import open_service, require_project, resolved_project
 from mammoth_cli.services.argspec import arg_spec
 from mammoth_cli.services.board_values import board_values, dashboard_link
@@ -896,6 +900,7 @@ _SDK_RULES: dict[str, Callable[[dict[str, Any]], None]] = {
     "agent.turn.rate": lambda k: agents_api.check_rating(
         str(k.get("rating") or ""), k.get("comment")
     ),
+    "dashboard.embed.lifetime.set": lambda k: dashboards_api.check_token_ttl(k.get("token_ttl")),
 }
 
 #: What the confirmation (and its refusal) names, where the command id alone would hide
@@ -924,6 +929,8 @@ _HANDLE_KEPT = frozenset(
         "dashboard.figure.rows",
         "dashboard.published.drill",
         "dashboard.published.rows",
+        # The bake job's result does not name the chart; the handle's dashboard_id does.
+        "dashboard.live-chart.create",
     }
 )
 
@@ -990,6 +997,15 @@ def generated_dashboard(invocation: Invocation) -> HandlerResult:
             )
 
     _check_sdk_rules(invocation.command_id, kwargs)
+    if (
+        invocation.project is not None
+        and spec is not None
+        and "project_id" not in kwargs
+        and any(field.name == "project_id" for field in spec.fields)
+    ):
+        # ``--project`` names the project a new board belongs to (live-chart create,
+        # template apply, v3 generate); without it the server picks the source's.
+        kwargs["project_id"] = invocation.project
 
     policy = str(record.get("confirmation") or POLICY_NONE)
     target = next((str(value) for value in positionals.values()), None)
@@ -1005,7 +1021,7 @@ def generated_dashboard(invocation: Invocation) -> HandlerResult:
                 invocation, policy=policy, action=action, target=str(auth.workspace_id)
             )
         data = service.call(_symbol(invocation), **kwargs)
-        handle = data
+        handle = data.model_dump(mode="json") if hasattr(data, "model_dump") else data
         data = _resolve_job(service, invocation, data)
         if invocation.command_id in _HANDLE_KEPT and isinstance(handle, dict):
             # The job's results are keyed by descriptor id; the handle says which
@@ -1019,6 +1035,8 @@ def generated_dashboard(invocation: Invocation) -> HandlerResult:
         if invocation.command_id in _VALUED_COMMANDS:
             data = _with_board_values(service, auth, positionals, data)
         forget(service)
+    if invocation.reveal_secrets and invocation.command_id in REVEAL_COMMANDS:
+        data = Revealed(normalize(data, redact_secrets=False))
     return data, _meta(invocation, auth.workspace_id)
 
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/file.py

@@ -464,6 +464,15 @@ def _dataset_status(service: Any, dataset_id: int) -> tuple[str, dict[str, Any]
     )
 
 
+#: An upload whose job finished without making any dataset.
+NO_DATASET_STATUS = "no_dataset"
+_NO_DATASET_MESSAGE = (
+    "The file was uploaded but no dataset was made from it. A PDF waits in the file list "
+    "as action_needed until its tables are extracted, which the CLI cannot do yet; do that "
+    "in the Mammoth app. Do not upload the file again."
+)
+
+
 def _upload_result(
     value: Any, read_status: Callable[[int], tuple[str, dict[str, Any] | None, str | None]]
 ) -> dict[str, Any]:
@@ -505,6 +514,12 @@ def _upload_result(
     result: dict[str, Any] = {"status": overall, "dataset_ids": ids, "datasets": datasets}
     if len(ids) == 1:
         result["dataset_id"] = ids[0]
+    if not ids:
+        # A PDF ends the upload job in ``action_needed`` with no dataset: its
+        # tables must be picked first (#255), so nothing here is ready.
+        result["status"] = NO_DATASET_STATUS
+        result["message"] = _NO_DATASET_MESSAGE
+        result["next_command"] = "mammoth file list"
     return result
 
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/schema.py

@@ -723,7 +723,16 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "workflow.save-cancel-step": "cancel one step of a running workflow save stop a save step",
     "view.export.runs": "export run history past runs of an export rows sent errors when it ran",
     "view.export.rest-fill": "propose REST API export settings from an API docs page url",
-    "view.summary": "summary of a dataview rows columns overview stats at a glance",
+    "workspace.user.list": (
+        "list users members of the workspace or of one project with --project, their roles "
+        "and status, who has access, my role in a project"
+    ),
+    # What was done to the view and what depends on it; column statistics are
+    # ``view data profile``.
+    "view.summary": (
+        "summary of what a dataview has had done to it and where it goes: pipeline steps "
+        "actions exports dashboards dependencies downstream, row and column counts"
+    ),
     "workspace.export-hosts.get": "hosts exports may send data to allowed export hosts policy",
     "workspace.export-hosts.set": "restrict or allow the hosts exports may send data to",
     "dashboard.email-updates.list": "email updates on dashboards I subscribe to in the workspace",
@@ -1228,11 +1237,16 @@ def _accepted_fields(record: dict[str, Any]) -> list[dict[str, Any]] | None:
         tuple(str(item) for item in record.get("operation_ids", []))
     )
     path_fields = local_path_fields(record["command_id"], record.get("positionals", []))
+    # A field an optional positional fills (``view summary VIEW_ID [DATASET_ID]``) is
+    # resolved by the command when both are omitted, as the input schema says.
+    fallbacks = {
+        item.falls_back_to_field for item in contract.positionals if item.falls_back_to_field
+    }
     return [
         {
             "name": field.name,
             "type": field.type_name,
-            "required": field.required,
+            "required": field.required and field.name not in fallbacks,
             "enum": field.enum_values,
             "default": field.default_value if field.has_default else None,
             "schema": (

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/view/export.py

@@ -87,7 +87,7 @@ def view_export_csv(invocation: Invocation) -> HandlerResult:
 def view_export_download(invocation: Invocation) -> HandlerResult:
     """Download a dataview to a local file as csv, xlsx, json, ndjson, xml, yaml or parquet.
 
-    Same as ``view export csv`` otherwise: ``--input '{"format": "xlsx", "output_path":
+    Same as ``view export csv`` otherwise: ``--input '{"file_type": "xlsx", "output_path":
     "out.xlsx"}'``; the default name carries the format's extension; an existing file is not
     replaced unless ``--overwrite``; embedded, the signed download URL is returned instead.
     """
@@ -251,6 +251,7 @@ def view_export_rest_fill(invocation: Invocation) -> HandlerResult:
 
     Mammoth's server fetches ``docs_url`` and reads it to propose the form values (never
     credentials). Nothing is configured or sent: the result is a suggestion to review.
+    It always waits for the job, for at most ``--job-timeout`` seconds.
     """
     project_id = require_project(invocation)
     dataview_id = _require_int_positional_at(invocation, 0, "dataview id")

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/view_ops.py

@@ -369,7 +369,6 @@ def _dispatch_view(
     prepare: Callable[[Any, int, dict[str, Any]], Any] | None = None,
     reduces_rows: bool = False,
     waits_for_run: bool = False,
-    apply_draft: bool = False,
     **kwargs: Any,
 ) -> HandlerResult:
     """Open the service, dispatch a View method call, and build the envelope.
@@ -378,10 +377,8 @@ def _dispatch_view(
     then waits for that task's own run to finish (see
     :func:`wait_for_added_task_run`) before ``after`` and the read-back, and
     carries that run as ``run``; a pipeline definition reading ``ready`` is not
-    proof the task ran. ``apply_draft`` (with ``waits_for_run``) makes a step
-    staged in draft mode run in this same call: the draft is submitted and the
-    wait is on the added task's own run. A draft that already held other staged
-    steps is left staged, because submitting would run steps the caller never named.
+    proof the task ran. A step staged in draft mode is never submitted here and has
+    no run to wait on: the draft stays the user's to submit.
 
     ``before(service, dataset_id)`` runs ahead of the call and its value is
     handed to ``after(service, dataset_id, state, data)``, which returns the
@@ -438,11 +435,6 @@ def _dispatch_view(
             if waits_for_run and dataset_id is not None
             else None
         )
-        held_steps = (
-            _draft_has_pending_changes(service, view_id)
-            if apply_draft and dataset_id is not None
-            else True
-        )
         rows_before = (
             _view_row_count(service, int(dataset_id), view_id, invocation.project)
             if auto_row_check and dataset_id is not None
@@ -482,11 +474,6 @@ def _dispatch_view(
             parents.remember(
                 _profile_name(invocation), auth.workspace_id, {view_id: int(dataset_id)}
             )
-        if apply_draft and not held_steps and dataset_id is not None and _is_staged(data):
-            service.call_view(view_id, "submit_draft", dataset_id=int(dataset_id))
-            data = {key: value for key, value in data.items() if key != "message"}
-            data["status"] = "done"
-            data["draft_applied"] = True
         settled = _settled_write(service, data) if dataset_id is not None else None
         if settled is not None:
             _forget_reads(service)  # the state read-back must see the view as the write left it
@@ -695,12 +682,6 @@ def _is_staged(data: Any) -> bool:
     return isinstance(data, dict) and data.get("status") == "staged"
 
 
-def _draft_has_pending_changes(service: Any, view_id: int) -> bool:
-    """Whether the view's draft already holds staged steps (``False`` outside draft mode)."""
-    status = service.call(_DRAFT_STATUS_SYMBOL, dataview_id=view_id)
-    return bool(status.get("has_pending_changes")) if isinstance(status, dict) else False
-
-
 def _mark_staged_in_draft(service: Any, dataset_id: int, view_id: int, data: Any) -> Any:
     """Answer ``status: staged`` for a write the SDK did not already stage.
 
@@ -2215,8 +2196,8 @@ def _keep_data(service: Any, dataset_id: int, state: Any, data: Any) -> Any:
 def view_transform_update_column(invocation: Invocation) -> HandlerResult:
     """Overwrite a column with a math expression in one call; ``column``, ``expression`` required.
 
-    ``view transform math`` with ``existing_column``, except that a step staged
-    in draft mode is submitted here and the result waits on its own task's run.
+    ``view transform math`` with ``existing_column``, with the result waiting on
+    its own task's run (a step staged in draft mode stays staged).
     """
     view_id = _view_id(invocation)
     document = invocation.load_input()
@@ -2228,7 +2209,7 @@ def view_transform_update_column(invocation: Invocation) -> HandlerResult:
         "existing_column": column,
     }
     return _math_into_column(
-        invocation, view_id, math_document, after=_keep_data, waits_for_run=True, apply_draft=True
+        invocation, view_id, math_document, after=_keep_data, waits_for_run=True
     )
 
 
@@ -2239,8 +2220,8 @@ _FIRST_WORD_PATTERN = r"^\S+"
 def view_transform_first_name(invocation: Invocation) -> HandlerResult:
     """Extract the first word of a text column, in one call. ``column`` is required.
 
-    ``view transform substring`` with the first-word regex, with the same draft
-    apply and own-task wait as ``view transform update-column``.
+    ``view transform substring`` with the first-word regex, with the same own-task
+    wait as ``view transform update-column``.
     """
     view_id = _view_id(invocation)
     document = invocation.load_input()
@@ -2256,7 +2237,6 @@ def view_transform_first_name(invocation: Invocation) -> HandlerResult:
         "substring",
         after=_keep_data,
         waits_for_run=True,
-        apply_draft=True,
         **kwargs,
     )
 

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/commands/workspace.py

@@ -202,9 +202,11 @@ def workspace_get(invocation: Invocation) -> HandlerResult:
 def workspace_list(invocation: Invocation) -> HandlerResult:
     """List accessible workspaces."""
     document = invocation.load_input() or {}
-    limit = int(document.get("limit", 100))
+    kwargs: dict[str, Any] = {"limit": int(document.get("limit", 100))}
+    if document.get("fields") is not None:
+        kwargs["fields"] = str(document["fields"])
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), limit=limit)
+        data = service.call(_symbol(invocation), **kwargs)
     return data, _meta(invocation, auth.workspace_id)
 
 
@@ -353,11 +355,14 @@ def workspace_user_list(invocation: Invocation) -> HandlerResult:
     """List users in the client's own workspace, with their roles and status.
 
     Asks for the backend's ``__full`` field set unless ``--input`` names another,
-    so each user carries ``user_roles`` and ``status``.
+    so each user carries ``user_roles`` and ``status``. An explicit ``--project``
+    keeps only that project's members (a saved default project does not).
     """
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {"fields": _USER_LIST_FIELDS}
-    _forward_optional(document, kwargs, ("fields", "project_id"))
+    _forward_optional(document, kwargs, ("fields",))
+    if invocation.project is not None:
+        kwargs["project_id"] = invocation.project
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
     return data, _meta(invocation, auth.workspace_id)

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/errors/envelope.py

@@ -59,6 +59,7 @@ CODE_CONFIRMATION_REQUIRED = "confirmation_required"
 CODE_CONFIRMATION_DECLINED = "confirmation_declined"
 CODE_AUTHENTICATION_FAILED = "authentication_failed"
 CODE_AUTHORIZATION_REQUIRED = "authorization_required"
+CODE_PLAN_LIMIT = "plan_limit"
 CODE_CONFLICT = "conflict"
 CODE_RETRYABLE = "retryable_error"
 CODE_OUTCOME_UNKNOWN = "outcome_unknown"
@@ -111,6 +112,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "feature_unavailable": "Mammoth no longer offers this feature.",
     "export_failed": "The export ran but ended in an error.",
     "export_not_found": "No export run was found for that request.",
+    "plan_limit": "The workspace's plan or usage limit doesn't allow this.",
     "pin_not_recorded": "The version pin could not be saved, so nothing was changed.",
     "has_dependents": "Other items still depend on this, so it was not deleted.",
     "delete_not_applied": "The delete was accepted but the item is still there.",

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/output/normalize.py

@@ -223,7 +223,9 @@ def normalize(value: Any, *, redact_secrets: bool = True) -> Any:
         result: dict[str, Any] = {}
         for key in sorted(value, key=str):
             str_key = str(key)
-            if redact_secrets and _is_secret_key(str_key):
+            # A boolean (``has_signing_secret``) only says whether a credential
+            # exists; it never is one.
+            if redact_secrets and _is_secret_key(str_key) and not isinstance(value[key], bool):
                 result[str_key] = REDACTED
             else:
                 result[str_key] = normalize(value[key], redact_secrets=redact_secrets)

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/runtime/invocation.py

@@ -91,6 +91,9 @@ class Invocation:
     #: ``--full`` on a compacted dashboard write: return the whole response
     #: (:mod:`mammoth_cli.runtime.compact`).
     full_output: bool = False
+    #: ``--reveal`` on a command that returns a once-shown credential: print it
+    #: unmasked (:mod:`mammoth_cli.runtime.reveal`).
+    reveal_secrets: bool = False
     #: ``last_modified_time`` of each export on the view, read before a pipeline write;
     #: verify waits for one to move (the backend re-validates exports after the run).
     exports_before: dict[int, str] | None = field(default=None, repr=False, compare=False)

mammoth_cli-2.2.98/mammoth_cli/runtime/reveal.py

@@ -0,0 +1,21 @@
+"""``--reveal`` on the commands whose result is a credential the API shows once.
+
+``dashboard embed secret rotate`` returns the new workspace signing secret and
+``dashboard embed preview-token create`` a token for the embed simulator. Key
+redaction masks both (``secret``, ``token``), which leaves a rotation with no
+usable secret. They stay masked by default, so a log or a shared transcript
+never holds them; ``--reveal`` prints them, the way ``client-app create`` shows
+its token.
+"""
+
+from __future__ import annotations
+
+REVEAL_FLAG = "--reveal"
+
+#: The commands that print their credential when given ``--reveal``.
+REVEAL_COMMANDS = frozenset(
+    {
+        "dashboard.embed.secret.rotate",
+        "dashboard.embed.preview-token.create",
+    }
+)

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/runtime/strict.py

@@ -39,6 +39,7 @@ from typing import Any
 
 from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
 from mammoth_cli.runtime.compact import COMPACT_COMMANDS, FULL_FLAG
+from mammoth_cli.runtime.reveal import REVEAL_COMMANDS, REVEAL_FLAG
 from mammoth_cli.services.argspec import FieldSpec
 from mammoth_cli.services.command_contract import (
     resolve_command_contract,
@@ -61,6 +62,8 @@ COMMAND_FLAGS: dict[str, frozenset[str]] = {
     "run": frozenset({"--continue"}),
     # The compacted dashboard writes: --full returns the whole response.
     **{command_id: frozenset({FULL_FLAG}) for command_id in COMPACT_COMMANDS},
+    # A once-shown credential is masked unless --reveal asks for it.
+    **{command_id: frozenset({REVEAL_FLAG}) for command_id in REVEAL_COMMANDS},
 }
 
 CODE_UNKNOWN_OPTION = "unknown_option"

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/runtime/verify.py

@@ -93,6 +93,8 @@ _UNSETTLED_REASON = (
 
 #: A write the CLI skipped because it would change nothing (see ``view transform``).
 _NO_CHANGE_STATUS = "no_change"
+#: ``file upload``'s status when its job made no dataset (``commands.file.NO_DATASET_STATUS``).
+_NO_DATASET_STATUS = "no_dataset"
 
 
 def with_verify(data: Any, invocation: Invocation | None = None) -> Any:
@@ -351,7 +353,7 @@ def _verify_and_reason(
     ``reason`` is set whenever ``verified`` is ``False`` (a failure or a
     no-op) and for a staged draft; it is ``None`` for an ordinary success.
     A failure never sets ``needs_user`` -- see :func:`_needs_user`, which
-    covers only the two outcomes serious enough to interrupt the caller.
+    covers only the outcomes serious enough to interrupt the caller.
     """
     if data.get("changed") is False:
         message = data.get("message")
@@ -431,7 +433,7 @@ def _needs_user(
     rows_before: int | None,
     rows_after: int | None,
 ) -> str | None:
-    """The only two outcomes worth interrupting the caller for.
+    """The few outcomes worth interrupting the caller for.
 
     ``needs_user`` means "a serious outcome the user must hear about before
     anything is built on it" -- never "something went wrong that you can
@@ -443,6 +445,10 @@ def _needs_user(
     """
     if not verified:
         return None
+    if data.get("status") == _NO_DATASET_STATUS:
+        # An upload that made no dataset (a PDF awaiting table extraction).
+        message = data.get("message")
+        return message if isinstance(message, str) else "The upload made no dataset."
     if rows_after == 0 and isinstance(rows_before, int) and rows_before > 0:
         return f"The change left the view with no rows (was {rows_before})."
     join_check = data.get("join_check")

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/services/argspec.py

@@ -70,10 +70,14 @@ class FieldSpec:
 
     @property
     def enum_values(self) -> list[str] | None:
-        """The member values, if this field's type is a string enum."""
+        """The member values, if this field's type is a string enum or a ``Literal`` of them."""
         target = self.resolved_type
         if isinstance(target, type) and issubclass(target, enum.Enum):
             return [member.value for member in target]
+        if get_origin(target) is typing.Literal:
+            values = get_args(target)
+            if values and all(isinstance(value, str) for value in values):
+                return list(values)
         return None
 
     @property

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/services/input_fields.py

@@ -62,6 +62,9 @@ _HANDLER_OWNED_FIELDS: dict[str, frozenset[str]] = {
     # ``job get`` is an immediate status read; only wait commands implement
     # the CLI's timeout/polling behavior.
     "job.get": frozenset({"timeout"}),
+    # ``view export rest-fill`` always waits for its job, bounded by ``--job-timeout``
+    # (``--return-running`` hands back the running job); the SDK's own switches are not inputs.
+    "view.export.rest-fill": frozenset({"wait", "timeout"}),
     # ``PipelineAPI.get_draft_status`` carries a legacy ``dataset_id`` alongside
     # the ``dataview_id`` the handler forwards from the view positional; the
     # handler never reads it, so it must not be advertised as an --input field.
@@ -105,6 +108,10 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     # bare ``<field>``: the values are the ones the API documents (OpenAPI enums, or
     # the SDK method's own docstring/validator), so each example is a call that works.
     "agent.message.set-request-kind": {"request_kind": "ask"},
+    # The sampled 1 is outside the server's 60..3600 seconds (#283).
+    "dashboard.embed.lifetime.set": {"token_ttl": 900},
+    # The format is the point of this command; csv has its own (#282).
+    "view.export.download": {"file_type": "xml"},
     "support.plan.update-entitlements": {"values": {"dashboardBranding": "no_branding"}},
     # Server-master routes: drill, rows behind a mark, describe-a-chart, chart types,
     # file routing and connector drafts.

{mammoth_cli-2.2.96 → mammoth_cli-2.2.98}/mammoth_cli/services/mapping.py

@@ -30,6 +30,7 @@ from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENTS,
     CODE_JOB_FAILED,
     CODE_OUTCOME_UNKNOWN,
+    CODE_PLAN_LIMIT,
     CODE_RESOURCE_NOT_FOUND,
     CODE_RETRYABLE,
     EMBEDDED_AUTH_HINT,
@@ -263,6 +264,21 @@ def _retry_hint(retry_after: str | None) -> str:
 #: A backend error ``name`` that refuses an action for lack of permission
 #: (``DASHBOARD_CREATE_NOT_ALLOWED``) arrives as a 400, not a 403.
 _NOT_ALLOWED_SUFFIX = "_NOT_ALLOWED"
+#: The generic permission refusal (4PERM002), which some routes send as a 400.
+_PERMISSION_ERROR_NAME = "PERMISSION_ERROR"
+
+#: Backend codes that refuse an action because of the workspace's plan or AI
+#: quota, not the user's permissions: no id or role change fixes them.
+_PLAN_LIMIT_CODES = frozenset(
+    {
+        "4SUBS101",  # FEATURE_NOT_AVAILABLE_ON_PLAN
+        "4SUBS102",  # CONNECTOR_NOT_AVAILABLE_ON_PLAN
+        "4SUBS103",  # PLAN_PAYMENT_REQUIRED
+        "4SUBS104",  # AI_QUOTA_EXHAUSTED
+        "4SUBS105",  # WORKSPACE_OVER_PLAN_LIMITS
+        "4SUBS106",  # PLAN_LIMIT_REACHED
+    }
+)
 
 
 def _not_allowed_reason(body: Any, status: int | None) -> str | None:
@@ -271,11 +287,24 @@ def _not_allowed_reason(body: Any, status: int | None) -> str | None:
         return None
     name = body.get("name")
     message = body.get("message")
-    if not isinstance(name, str) or not name.endswith(_NOT_ALLOWED_SUFFIX):
+    if not isinstance(name, str) or not (
+        name.endswith(_NOT_ALLOWED_SUFFIX) or name == _PERMISSION_ERROR_NAME
+    ):
         return None
     return message if isinstance(message, str) and message else name
 
 
+def _plan_limit_reason(body: Any, status: int | None) -> str | None:
+    """The backend's own words when a 4xx refuses for the plan or AI quota."""
+    if status is None or not 400 <= status < 500 or not isinstance(body, dict):
+        return None
+    backend_code = body.get("error_code") or body.get("code")
+    if backend_code not in _PLAN_LIMIT_CODES:
+        return None
+    message = body.get("message")
+    return message if isinstance(message, str) and message else str(backend_code)
+
+
 def _backend_message(body: Any, status: int | None) -> str | None:
     """The backend's own words for a 4xx: message, reason under it, field errors, then code."""
     if status is None or not 400 <= status < 500 or not isinstance(body, dict):
@@ -632,6 +661,20 @@ def map_sdk_exception(
                 request_id=request_id,
                 recovery_commands=[token_login],
             )
+        plan_limit = _plan_limit_reason(exc.response_body, status)
+        if plan_limit is not None:
+            return CliError(
+                code=CODE_PLAN_LIMIT,
+                message=plan_limit,
+                exit_status=EXIT_AUTH,
+                hint=(
+                    "The workspace's plan or monthly AI quota does not cover this; the ids "
+                    "and permissions are not the problem. Do not retry: tell the user, who "
+                    "can upgrade the plan or ask Mammoth support to extend the quota."
+                ),
+                details=details,
+                request_id=request_id,
+            )
         if status == 403:
             return CliError(
                 code=CODE_AUTHORIZATION_REQUIRED,