mammoth-cli 2.2.53__tar.gz → 2.2.54__tar.gz

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.53
+Version: 2.2.54
 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.9,>=0.8.27
+Requires-Dist: mammoth-io<0.9,>=0.8.28
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/__main__.py

@@ -8,10 +8,9 @@ launch symbol that does not change when the application wiring moves.
 
 from __future__ import annotations
 
+import sys
 from typing import Any
 
-from mammoth_cli.app import app
-
 
 def main() -> Any:
     """Run the Mammoth CLI application.
@@ -20,6 +19,14 @@ def main() -> Any:
         The value returned by the Typer application, which the runtime uses as
         the process exit code.
     """
+    if sys.argv[1:] == ["--version"]:
+        # The answer needs none of the command tree; skip building it.
+        from mammoth_cli import __version__
+
+        sys.stdout.write(f"{__version__}\n")
+        return 0
+    from mammoth_cli.app import app
+
     return app()
 
 

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/app.py

@@ -19,6 +19,7 @@ import re
 import sys
 from collections.abc import Callable, Sequence
 from dataclasses import replace
+from difflib import get_close_matches
 from functools import cache
 from typing import Annotated, Any
 
@@ -383,9 +384,33 @@ class _EnvelopeGroup(TyperGroup):
     def get_command(self, ctx: Any, cmd_name: str) -> Any:
         eager: dict[str, Any] = self.__dict__.setdefault("_eager_commands", {})
         if cmd_name not in eager and cmd_name in _LAZY_GROUP_NAMES:
+            if self.__dict__.get("_listing_help"):
+                return _group_stub(cmd_name)
             eager[cmd_name] = _load_top_level_group(cmd_name)
         return eager.get(cmd_name)
 
+    def resolve_command(self, ctx: Any, args: list[str]) -> Any:
+        # Typer's override suggests close names from ``self.commands``, which
+        # builds every group; the names alone are all a suggestion needs.
+        try:
+            return self._click_resolve_command(ctx, args)
+        except _typer_click_exceptions.UsageError as error:
+            if self.suggest_commands and args:
+                matches = get_close_matches(args[0], self.list_commands(ctx))
+                if matches:
+                    suggestions = ", ".join(f"{m!r}" for m in matches)
+                    error.message = f"{error.message.rstrip('.')}. Did you mean {suggestions}?"
+            raise
+
+    def format_help(self, ctx: Any, formatter: Any) -> None:
+        # Root ``--help`` only needs each group's name, panel and one-line
+        # description; building all ~550 commands to print them cost seconds.
+        self.__dict__["_listing_help"] = True
+        try:
+            super().format_help(ctx, formatter)
+        finally:
+            self.__dict__["_listing_help"] = False
+
     def main(self, *args: Any, **kwargs: Any) -> Any:
         if not kwargs.get("standalone_mode", True):
             return super().main(*args, **kwargs)
@@ -447,11 +472,16 @@ class _EnvelopeGroup(TyperGroup):
                     )
                 elif isinstance(error, _typer_click_exceptions.NoSuchOption):
                     option = getattr(error, "option_name", None) or "unknown"
+                    close = getattr(error, "possibilities", None) or []
                     report = CliError(
                         code="unknown_option",
                         message=f"Unknown option '{option}'.",
                         exit_status=EXIT_USAGE,
-                        hint="Check the command schema with 'mammoth schema get'.",
+                        hint=(
+                            f"Did you mean {' or '.join(sorted(close))}?"
+                            if close
+                            else "Check the command schema with 'mammoth schema get'."
+                        ),
                         details={"option": option},
                     )
                 elif isinstance(error, _typer_click_exceptions.BadParameter):
@@ -1032,6 +1062,15 @@ def _command_tree() -> tuple[dict[tuple[str, ...], str], frozenset[tuple[str, ..
     return path_to_command, frozenset(prefixes & path_to_command.keys())
 
 
+def _leaf_context_settings(command_id: str) -> dict[str, bool]:
+    """Click settings for one command: a bespoke command declares every option it
+    accepts, so Click itself rejects an unknown one; a generic leaf collects its
+    trailing tokens and validates them in :func:`validate_extra_args`."""
+    if command_id in BESPOKE:
+        return {}
+    return {"allow_extra_args": True, "ignore_unknown_options": True}
+
+
 def _group_typer(tokens: tuple[str, ...], command_id: str | None) -> typer.Typer:
     if command_id is not None:
         # This node is both a group and an invocable command.
@@ -1088,7 +1127,7 @@ def _populate(base: tuple[str, ...], group: typer.Typer) -> None:
             name=tokens[-1],
             help=_command_help(command_id, record),
             rich_help_panel=_ROOT_HELP_PANELS.get(tokens[0]) if len(tokens) == 1 else None,
-            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+            context_settings=_leaf_context_settings(command_id),
         )(callback)
 
 
@@ -1121,6 +1160,16 @@ def _load_top_level_group(name: str) -> Any:
     return typer.main.get_group_from_info(info, **_LAZY_SETTINGS)
 
 
+def _group_stub(name: str) -> Any:
+    """A placeholder group carrying only what the root ``--help`` listing prints."""
+    return TyperGroup(
+        name=name,
+        help=_GROUP_DESCRIPTIONS.get(name, f"Commands for {name}."),
+        rich_help_panel=_ROOT_HELP_PANELS.get(name),
+        rich_markup_mode=_LAZY_SETTINGS["rich_markup_mode"],
+    )
+
+
 def build_app() -> typer.Typer:
     """Construct the Typer command tree from the command manifests.
 
@@ -1160,7 +1209,7 @@ def build_app() -> typer.Typer:
             name=name,
             help=_command_help(command_id, command_by_id(command_id)),
             rich_help_panel=_ROOT_HELP_PANELS.get(name),
-            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+            context_settings=_leaf_context_settings(command_id),
         )(BESPOKE.get(command_id) or _build_leaf(command_id))
     _LAZY_GROUP_NAMES[:] = lazy
     _LAZY_SETTINGS.update(

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -312,6 +312,8 @@ Result: `ViewDerivativeCreateResult`; mutation `benign_mutation`, confirmation `
 
 Status on release: ran once on CLI 2.0.24 — payload probe 2026-09-19: exit 0 on release with CLI 2.0.24. Created derivative id=6 on view 123 (project 52, dataset 104) with the column INTERNAL name as ARGUMENT; metric_status DONE on read-back. The same call with the display name reproduces the HTTP 500…
 
+A METRIC shows as an explore-panel card via `display_properties`; the CLI defaults it to the metric card, and the result's `card` says whether one exists.
+
 ### `view.derivative.data`
 
 Run: `mammoth view derivative data`. Exact input fields: `mammoth schema get view.derivative.data`.

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/auth.py

@@ -23,7 +23,7 @@ import typer
 from pydantic import ValidationError
 
 from mammoth_cli.context import credentials, oauth, profiles, resolver
-from mammoth_cli.context.endpoint import resolve_base_url
+from mammoth_cli.context.endpoint import DEFAULT_SERVER_PREFIX, resolve_base_url
 from mammoth_cli.context.resolver import ResolvedAuth, resolve_auth
 from mammoth_cli.contracts.auth import LoginRequest
 from mammoth_cli.errors.envelope import (
@@ -143,6 +143,14 @@ def _masked_receipt(value: str) -> str:
     return f"{len(value)} characters, ending in …{value[-4:]}"
 
 
+def _ask(label: str, **options: Any) -> str:
+    """Prompt once; a closed stdin (Ctrl-D, EOF) is a usage error, not a crash."""
+    try:
+        return str(typer.prompt(label, **options))
+    except typer.Abort:
+        raise _no_choice(label) from None
+
+
 def _prompt_secret(label: str) -> str:
     """Prompt for one secret with hidden input, then confirm what was captured.
 
@@ -152,7 +160,7 @@ def _prompt_secret(label: str) -> str:
     entry is rejected here, and a masked receipt (length and last four
     characters, never the value) is printed to stderr as feedback.
     """
-    value = typer.prompt(label, hide_input=True).strip()
+    value = _ask(label, hide_input=True).strip()
     if not value:
         raise CliError(
             code="login_input_required",
@@ -298,22 +306,65 @@ def _choose_method(
         return method
     if invocation.input_file is not None or blockers:
         return "token"
-    if not oauth.has_client_id(server_prefix):
-        return "token"
+    available = oauth.has_client_id(server_prefix)
+    prefix = server_prefix if server_prefix is not None else DEFAULT_SERVER_PREFIX
+    browser_note = "recommended" if available else f"(not yet available on {prefix})"
+    device_note = "no browser on this machine" if available else browser_note
     typer.echo("How do you want to sign in?", err=True)
-    typer.echo("  1) Browser (OAuth)      recommended", err=True)
-    typer.echo("  2) Device code          no browser on this machine", err=True)
+    typer.echo(f"  1) Browser (OAuth)      {browser_note}", err=True)
+    typer.echo(f"  2) Device code          {device_note}", err=True)
     typer.echo("  3) Paste an API token   for CI and scripts", err=True)
-    choice = typer.prompt("Choose", default="1", show_default=False).strip()
-    methods = {"1": "oauth", "2": "device", "3": "token"}
-    if choice not in methods:
-        raise CliError(
-            code="invalid_login_method",
-            message=f"'{choice}' is not one of the choices.",
-            exit_status=EXIT_USAGE,
-            hint="Enter 1 for the browser, 2 for a device code or 3 to paste an API token.",
-        )
-    return methods[choice]
+    default = "1" if available else "3"
+    if sys.stdin.isatty():
+        return _choose_by_keypress(default)
+    choice = _ask("Choose", default=default, show_default=False).strip()
+    if choice not in _METHOD_KEYS:
+        raise _bad_choice(choice)
+    return _METHOD_KEYS[choice]
+
+
+_METHOD_KEYS = {"1": "oauth", "2": "device", "3": "token"}
+_METHOD_LABELS = {"1": "Browser (OAuth)", "2": "Device code", "3": "API token"}
+
+
+def _bad_choice(choice: str) -> CliError:
+    return CliError(
+        code="invalid_login_method",
+        message=f"'{choice}' is not one of the choices.",
+        exit_status=EXIT_USAGE,
+        hint="Enter 1 for the browser, 2 for a device code or 3 to paste an API token.",
+    )
+
+
+def _choose_by_keypress(default: str) -> str:
+    """Read one key on a terminal: 1, 2 or 3 selects at once, Enter takes ``default``.
+
+    Any other key asks once more, then errors; Ctrl-C and Ctrl-D are a usage error.
+    """
+    key = ""
+    for _attempt in range(2):
+        typer.echo("Choose: ", nl=False, err=True)
+        try:
+            key = typer.getchar()
+        except (KeyboardInterrupt, EOFError):
+            typer.echo("", err=True)
+            raise _no_choice() from None
+        if key in ("\r", "\n"):
+            key = default
+        if key in _METHOD_KEYS:
+            typer.echo(f"{key} {_METHOD_LABELS[key]}", err=True)
+            return _METHOD_KEYS[key]
+        typer.echo("", err=True)
+    raise _bad_choice(key)
+
+
+def _no_choice(label: str = "choice") -> CliError:
+    return CliError(
+        code="login_input_required",
+        message=f"No {label} was entered.",
+        exit_status=EXIT_USAGE,
+        hint="Pass --method oauth|device|token, or --input FILE for a non-interactive login.",
+    )
 
 
 def _iso(epoch: int) -> str:

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/client_app.py

@@ -22,10 +22,13 @@ from typing import Any
 
 from mammoth.exceptions import MammothModelDriftWarning
 
+from mammoth_cli.context import credentials, oauth, profiles
+from mammoth_cli.context.endpoint import resolve_base_url
 from mammoth_cli.errors.envelope import (
     CODE_MISSING_ARGUMENT,
     CODE_MISSING_FIELD,
     CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_API,
     EXIT_USAGE,
     CliError,
 )
@@ -254,6 +257,37 @@ def client_app_delete(invocation: Invocation) -> HandlerResult:
     enforce_confirmation(
         invocation, policy=POLICY_PROMPT_OR_YES, action=f"delete client app {client_key}"
     )
+    own = _own_oauth_session(invocation, client_key)
+    if own is not None:
+        return _revoke_own_grant(invocation, own)
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), client_key=client_key)
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def _own_oauth_session(invocation: Invocation, client_key: str) -> credentials.OAuthSession | None:
+    """The caller's browser-login session when ``client_key`` is the client it signed in as."""
+    credential = credentials.load_credential(invocation.profile or profiles.get_selected())
+    session = credential.oauth if credential is not None else None
+    return session if session is not None and session.client_id == client_key else None
+
+
+def _revoke_own_grant(invocation: Invocation, session: credentials.OAuthSession) -> HandlerResult:
+    """Disconnect the caller's own grant: the workspace client-app route does not know it."""
+    profile_name = invocation.profile or profiles.get_selected()
+    record = profiles.get_profile(profile_name)
+    if record is None:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"Profile {profile_name} is not configured.",
+            exit_status=EXIT_USAGE,
+        )
+    base_url = resolve_base_url(record.server_prefix)
+    if not oauth.is_fresh(session):
+        session = oauth.refresh_session(profile_name, base_url)
+    problem = oauth.revoke_grant(base_url, session)
+    if problem is not None:
+        raise CliError(code="oauth_grant_revoke_failed", message=problem, exit_status=EXIT_API)
+    return {"revoked": "own OAuth grant", "grant_id": session.grant_id}, _meta(
+        invocation, record.workspace_id, resolved_project(invocation)
+    )

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/dashboard.py

@@ -14,7 +14,6 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Literal, cast
 
-from mammoth.models.dashboards import AddPagesSpec
 from pydantic import ValidationError
 
 from mammoth_cli.commands.view import _FIND_DATASET_SYMBOL, view_profiles
@@ -733,6 +732,8 @@ def generated_dashboard(invocation: Invocation) -> HandlerResult:
     # AddPages has a release-level minItems constraint that must be enforced
     # before confirmation or transport.
     if invocation.command_id == "dashboard.pages.add" and "body" in kwargs:
+        from mammoth.models.dashboards import AddPagesSpec
+
         try:
             kwargs["body"] = AddPagesSpec.model_validate(kwargs["body"]).model_dump(
                 mode="json", exclude_none=True

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/project.py

@@ -134,11 +134,25 @@ def project_list(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 
+#: What ``project get`` reads: the project's own record, not what it holds.
+_PROJECT_GET_COVERS = (
+    "the project's id and name only; its datasets and views are not counted here "
+    "(mammoth dataset list --project {project_id})"
+)
+#: What ``project resource-status`` reads: only work happening right now.
+_RESOURCE_STATUS_COVERS = (
+    "resources with a task in flight right now; empty in_flight does not mean the project has "
+    "no resources (mammoth dataset list --project {project_id})"
+)
+
+
 def project_get(invocation: Invocation) -> HandlerResult:
     """Get one project by id (positional or active project)."""
     project_id = _project_id(invocation)
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), project=project_id)
+    if isinstance(data, dict):
+        data = {**data, "covers": _PROJECT_GET_COVERS.format(project_id=project_id)}
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -185,10 +199,15 @@ def project_memory_remove(invocation: Invocation) -> HandlerResult:
 
 
 def project_resource_status(invocation: Invocation) -> HandlerResult:
-    """Report the status of a project's resources."""
+    """Report the project's in-flight resource tasks, named as such."""
     project_id = _project_id(invocation)
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), project_id=project_id)
+    in_flight = data.get("status") if isinstance(data, dict) else None
+    data = {
+        "in_flight": in_flight if in_flight is not None else {},
+        "covers": _RESOURCE_STATUS_COVERS.format(project_id=project_id),
+    }
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/registry.py

@@ -898,12 +898,11 @@ HANDLERS: dict[str, Handler] = {
 }
 
 # Dashboard operations generated from the reviewed OpenAPI inventory share one
-# manifest-driven handler. Existing authored handlers remain authoritative.
-from mammoth.api.dashboard_generated import GENERATED_METHODS  # noqa: E402
-
-_GENERATED_DASHBOARD_SYMBOLS = {
-    f"mammoth.api.dashboards.DashboardsAPI.{method}" for method in GENERATED_METHODS
-}
+# manifest-driven handler. Existing authored handlers remain authoritative, so
+# ``setdefault`` only fills the dashboard commands that have none. Matching on
+# the SDK symbol prefix (rather than importing the generated method list) keeps
+# the generated dashboard models off the startup import path.
+_DASHBOARD_SDK_PREFIX = "mammoth.api.dashboards.DashboardsAPI."
 for _record in load_commands():
-    if _record.get("sdk_symbol") in _GENERATED_DASHBOARD_SYMBOLS:
+    if str(_record.get("sdk_symbol", "")).startswith(_DASHBOARD_SDK_PREFIX):
         HANDLERS.setdefault(str(_record["command_id"]), dashboard_cmd.generated_dashboard)

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/schema.py

@@ -337,8 +337,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "window rank row number running total cumulative sum moving average lag lead "
         "previous next row partition"
     ),
-    # The web app's column Explore cards: what is trending, how a column is
-    # spread, its top values, a count over time.
+    # Reads a column's value distribution: what is trending, how a column is
+    # spread, its top values, a count over time. It opens no card in the UI.
     "view.data.explore": (
         "explore trend trends trending over time per day week month quarter year by date "
         "distribution spread histogram top most common frequent values breakdown share "
@@ -572,7 +572,10 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "condition checkpoint value changes"
     ),
     "view.data-check.create": "data quality check rule validate rows match condition flag",
-    "view.derivative.create": "metric kpi number single value to check track daily monitor",
+    "view.derivative.create": (
+        "metric kpi number single value to check track daily monitor add a metric "
+        "sum of column explore panel card metric card"
+    ),
     "view.draft.auto-run": (
         "stop prevent re-running rerun automatically when source changes auto run enable disable"
     ),

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/upgrade.py

@@ -361,6 +361,7 @@ def perform(invocation: Invocation, *, check: bool, target_version: str | None)
         invocation,
         policy=POLICY_PROMPT_OR_YES,
         action=f"upgrade {PACKAGE_NAME} to {action_target} using {manager}",
+        default=True,
     )
     result = run_upgrade(command)
     if result.returncode != 0:

{mammoth_cli-2.2.53 → mammoth_cli-2.2.54}/mammoth_cli/commands/view.py

@@ -29,9 +29,6 @@ from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
 from typing import Any
 
-from mammoth.models.exports import ExportStatus
-from mammoth.view import ViewExport
-
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
@@ -86,6 +83,7 @@ _DATASET_GET_SYMBOL = "mammoth.api.datasets.DatasetsAPI.get"
 # data-read commands can take the view id alone and fill the dataset for the
 # caller. See :data:`mammoth_cli.services.positionals.POSITIONAL_OVERRIDES`.
 _FIND_DATASET_SYMBOL = "mammoth.api.pipeline.PipelineAPI.find_dataset_for_dataview"
+_EXPLORE_PANEL_GET_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.explore_panel"
 _WAIT_FOR_PIPELINE_SYMBOL = "mammoth.api.pipeline.PipelineAPI.wait_for_pipeline"
 _DATASET_ID_FIELD = "dataset_id"
 _DRAFT_OPERATIONS = frozenset({"enter", "exit", "submit", "discard"})
@@ -368,6 +366,9 @@ def _read_meta(
         project_id=project_id,
         fields="__min",
     )
+    # The read just proved this dataset holds the view; keep the pair so the
+    # next command on it (a transform) needs no ``dataset_id`` of its own.
+    parents.remember(_profile_name(invocation), workspace_id, {view_id: dataset_id})
     dataset = service.call(
         _DATASET_GET_SYMBOL, dataset_id=dataset_id, project_id=project_id, fields="id,name"
     )
@@ -1115,6 +1116,15 @@ def view_update(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _read_explore_panel(
+    service: Any, symbol: str, dataset_id: int, dataview_id: int, project_id: int
+) -> Any:
+    """The Explore panel the caller saved on a view (``{}`` when none is saved)."""
+    return service.call(
+        symbol, dataset_id=dataset_id, dataview_id=dataview_id, project_id=project_id
+    )
+
+
 def view_explore_panel_get(invocation: Invocation) -> HandlerResult:
     """Read the Explore panel the caller saved on a view (empty when none is saved)."""
     project_id = require_project(invocation)
@@ -1122,17 +1132,14 @@ def view_explore_panel_get(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input() or {}
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
-        data = service.call(
-            _symbol(invocation),
-            dataset_id=dataset_id,
-            dataview_id=dataview_id,
-            project_id=project_id,
+        data = _read_explore_panel(
+            service, _symbol(invocation), dataset_id, dataview_id, project_id
         )
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
 def view_explore_panel_set(invocation: Invocation) -> HandlerResult:
-    """Replace the caller's saved Explore panel with the ``panel`` input field."""
+    """Replace the caller's saved Explore panel; the result carries the panel read back after."""
     project_id = require_project(invocation)
     dataview_id = _require_int_positional_at(invocation, 0, "view id")
     document = invocation.load_input() or {}
@@ -1146,7 +1153,10 @@ def view_explore_panel_set(invocation: Invocation) -> HandlerResult:
             panel=panel,
             project_id=project_id,
         )
-    return data, _meta(invocation, auth.workspace_id, project_id)
+        saved = _read_explore_panel(
+            service, _EXPLORE_PANEL_GET_SYMBOL, dataset_id, dataview_id, project_id
+        )
+    return {**data, "panel": saved}, _meta(invocation, auth.workspace_id, project_id)
 
 
 def _untyped_patch_error(invocation: Invocation) -> CliError:
@@ -2204,7 +2214,7 @@ def _explore_range(
 
 
 def view_data_explore(invocation: Invocation) -> HandlerResult:
-    """Explore one column like the web app's Explore card (read-only): DATE counts per ``level`` bucket (AUTO, SECOND to MILLENNIUM), NUMERIC per power-of-10 ``level``, TEXT top values (``limit`` 20), each with ``count`` and ``percentage``; ``metric`` (a column plus SUM/AVG/MIN/MAX/STDDEV/COUNT/DISTINCT_COUNT) adds a per-bucket value, ``percentage_of`` "metric" shares by it, ``sort`` count_/value_/metric_ + asc/desc, ``condition`` filters first (include, exclude, blanks, range, contains; an exclude drops blank rows the card keeps, so or it with IS_EMPTY; drill down = finer ``level`` + ``condition`` on the bucket), ``limit``/``offset`` page, ``range`` true adds the exact earliest and latest value, ``cumulative`` a running total; ``-o csv`` saves the card's values; to put it on a dashboard say it in words to 'dashboard chat edit'.
+    """Read one column's value distribution (read-only; opens and changes no card in the UI, that is ``view explore-panel set``): DATE counts per ``level`` bucket (AUTO, SECOND to MILLENNIUM), NUMERIC per power-of-10 ``level``, TEXT top values (``limit`` 20), each with ``count`` and ``percentage``; ``metric`` (a column plus SUM/AVG/MIN/MAX/STDDEV/COUNT/DISTINCT_COUNT) adds a per-bucket value, ``percentage_of`` "metric" shares by it, ``sort`` count_/value_/metric_ + asc/desc, ``condition`` filters first (include, exclude, blanks, range, contains; an exclude drops blank rows the card keeps, so or it with IS_EMPTY; drill down = finer ``level`` + ``condition`` on the bucket), ``limit``/``offset`` page, ``range`` true adds the exact earliest and latest value, ``cumulative`` a running total; ``-o csv`` saves the values; to put it on a dashboard say it in words to 'dashboard chat edit'.
 
     Read-only: computes and returns the result without adding a task to the
     view's pipeline or otherwise changing it. Buckets by the column's type --
@@ -2759,12 +2769,40 @@ def view_data_check_update(invocation: Invocation) -> HandlerResult:
 # ---------------------------------------------------------------------------
 
 
+_METRIC_CARD_BASE: dict[str, Any] = {
+    "FORMAT_INFO": {"RESULT": {}},
+    "IS_FORMAT_INFO_DIRTY": False,
+    "LOCKED": False,
+    "type": "metric",
+}
+
+
+def _with_metric_card(body: Any) -> Any:
+    """Default a METRIC derivative's ``display_properties`` to its explore-panel card.
+
+    Without it the API stores ``display_properties: null``, which the explore
+    panel reads as "no card". An explicit value (including ``{}``) is kept.
+    """
+    param = body.get("param") if isinstance(body, dict) else None
+    metric = param.get("METRIC") if isinstance(param, dict) else None
+    if not isinstance(metric, dict) or body.get("display_properties") is not None:
+        return body
+    return {
+        **body,
+        "display_properties": {**_METRIC_CARD_BASE, "info": {"title": metric.get("AS")}},
+    }
+
+
 def view_derivative_create(invocation: Invocation) -> HandlerResult:
-    """Create a derivative on a dataview. ``body`` is required."""
+    """Create a derivative on a dataview. ``body`` is required.
+
+    A METRIC with no ``display_properties`` gets the metric card config so it
+    shows in the explore panel; the result's ``card`` says whether a card exists.
+    """
     project_id = require_project(invocation)
     dataview_id = _require_int_positional_at(invocation, 0, "view id")
     document = invocation.load_input()
-    body = _require_field(document, "body")
+    body = _with_metric_card(_require_field(document, "body"))
     assert document is not None
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
@@ -2775,7 +2813,8 @@ def view_derivative_create(invocation: Invocation) -> HandlerResult:
             body=body,
             project_id=project_id,
         )
-    return data, _meta(invocation, auth.workspace_id, project_id)
+    card = bool(body.get("display_properties")) if isinstance(body, dict) else False
+    return {**data, "card": card}, _meta(invocation, auth.workspace_id, project_id)
 
 
 def view_derivative_data(invocation: Invocation) -> HandlerResult:
@@ -3275,6 +3314,8 @@ def _end_of_pipeline_exports(
         dataset_id=dataset_id,
         end_of_pipeline=True,
     )
+    from mammoth.models.exports import ExportStatus
+
     fired: list[dict[str, Any]] = []
     source_columns: Any = None
     for export in getattr(listing, "exports", None) or []:
@@ -3920,6 +3961,8 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
     # reviewed trigger controls may flow through its **kwargs extension point;
     # using a union of every destination's fields would silently accept, for
     # example, email-only fields on a database export.
+    from mammoth.view import ViewExport
+
     signature = inspect.signature(getattr(ViewExport, method))
     explicit_fields = {
         name
@@ -4135,6 +4178,8 @@ def _existing_internal_dataset_export(
     and the list endpoint does not filter on status, so a deleted export
     would otherwise block every later export into that target forever.
     """
+    from mammoth.models.exports import ExportStatus
+
     listing = service.call(
         _EXPORTS_LIST_SYMBOL,
         dataview_id=dataview_id,