mammoth-cli 1.0.0__py3-none-any.whl

mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mammoth-cli
+description: Drive the Mammoth Analytics platform from the command line. Use for authenticating, browsing projects and datasets, running pipeline transformations and exports, and any automated or agent task that needs deterministic JSON output and safe, confirmable mutations.
+---
+
+# Mammoth CLI
+
+The `mammoth` command controls the Mammoth Analytics platform through the public
+`mammoth-io` SDK. It is built for autonomous agents: every command supports
+deterministic machine output, promptless operation, and stable error envelopes.
+
+## Golden rules for agents
+
+1. Always pass `--output json` and `--no-input`. Never rely on a prompt.
+2. Discover, do not guess. Use `mammoth capability list` and `mammoth schema get`
+   to learn a command before you run it.
+3. Read the exit code, not the text. `0` ok, `2` usage, `4` auth, `5` not found,
+   `6` conflict, `7` retryable, `1` other API error, `130` interrupt.
+4. Confirm mutations explicitly. Destructive commands need `--yes`; high-impact
+   commands also need `--confirm TARGET`. There is no interactive fallback under
+   `--no-input`.
+5. Never put a secret on the command line. Pass credentials through
+   `mammoth auth login` (prompt or environment) and structured secrets through
+   `--input`.
+
+## Authenticate
+
+```bash
+export MAMMOTH_API_KEY=... MAMMOTH_API_SECRET=... MAMMOTH_WORKSPACE_ID=4
+mammoth doctor --output json --no-input        # verify credentials + endpoint
+```
+
+Credentials resolve in this order: explicit login, then environment, then the
+saved profile. The endpoint defaults to the `app-eu` server prefix. See
+[references/auth.md](references/auth.md).
+
+## Select a project
+
+Most dataset, folder, view, and pipeline commands run inside a project.
+
+```bash
+mammoth context project use 180 --output json --no-input   # save the active project
+mammoth project list --output json --no-input              # or pass --project 180
+```
+
+## Machine output and structured input
+
+Every command returns `{schema_version, data, meta}` on stdout and a stable
+`{schema_version, error:{code, message, hint, ...}}` on stderr. Feed multi-field
+requests through one document:
+
+```bash
+mammoth view transform math 1039 --project 180 --output json --no-input \
+  --input '{"expression": "price * qty", "new_column": "total"}'
+```
+
+See [references/machine-output.md](references/machine-output.md) and
+[references/input.md](references/input.md).
+
+A transform that takes a nested request is driven the same way. Bulk-replace
+maps many search values to one replacement, across one or more columns:
+
+```bash
+mammoth view transform bulk-replace VIEW_ID \
+  --project PROJECT_ID \
+  --input '{
+    "columns": ["Status"],
+    "mapping": [
+      {"search": ["In progress", "Pending"], "replace": "Open"}
+    ],
+    "match_case": false,
+    "match_words": true
+  }' \
+  --output json --no-input
+```
+
+- `columns` and `mapping` are required; each mapping needs `search` (a list) and
+  `replace`.
+- `match_case` defaults to `true`; `match_words` defaults to `false`.
+- `condition` is optional (restrict the rows the replacement touches).
+- Run `mammoth schema get view.transform.bulk-replace --output json --no-input`
+  for the full request shape.
+
+## Safe mutations
+
+```bash
+mammoth dataset delete 2340 --project 180 --output json --no-input --yes
+mammoth workspace delete 9 --output json --no-input --yes --confirm 9
+```
+
+See [references/safety.md](references/safety.md).
+
+## Jobs, drafts, and cleanup
+
+Long operations return a job. A command's `wait_policy` (see `mammoth schema
+get`) tells you what to expect: `always_wait` and `start_or_wait` commands
+resolve the job for you and return the final result; only a `returns_job`
+command normally needs you to wait on the job id explicitly. Draft mode batches
+pipeline edits before submitting. Always delete resources you created in a
+shared project. See [references/jobs-drafts.md](references/jobs-drafts.md) and
+[references/recovery.md](references/recovery.md).
+
+## Discover everything
+
+```bash
+mammoth capability list --output json --no-input     # every operation
+mammoth schema list --output json --no-input         # every command's schema
+mammoth schema get view.transform.filter --output json --no-input
+```

mammoth_cli/bundled_skill/mammoth-cli/references/auth.md

@@ -0,0 +1,27 @@
+# Authentication and profiles
+
+Required: API key, API secret, workspace id. Optional: a one-label server
+prefix (default `app-eu`, resolving to `https://app-eu.mammoth.io/api/v2`).
+
+## Precedence
+1. Explicit credentials given to the current command (secure prompt or stdin).
+2. Environment: `MAMMOTH_API_KEY`, `MAMMOTH_API_SECRET`, `MAMMOTH_WORKSPACE_ID`
+   (all three required together), plus optional `MAMMOTH_SERVER_PREFIX`. Setting
+   only some of the three is rejected (`incomplete_environment_auth`) rather than
+   falling back to a saved profile.
+3. The selected or `--profile` profile's saved credentials.
+
+The only supported configuration is the API key, API secret, workspace id, and
+an optional one-label server prefix (default `app-eu`). There is no base-url
+override.
+
+## Commands
+```bash
+mammoth auth login --output json --no-input      # stores secret in the OS keyring
+mammoth auth status --output json --no-input
+mammoth auth logout --profile default --output json --no-input --yes
+```
+
+Secrets live in the OS keyring (or a `0600` file fallback). They are never
+printed, logged, or included in any envelope. Never pass a secret as a plain
+argument; use the prompt, environment, or `--input`.

mammoth_cli/bundled_skill/mammoth-cli/references/input.md

@@ -0,0 +1,24 @@
+# Structured input
+
+Drive multi-field commands with one strict document instead of many flags.
+
+```bash
+mammoth folder create --project 180 --output json --no-input \
+  --input '{"name": "Reports", "parent_resource_id": "r_root"}'
+
+mammoth view transform filter 1039 --project 180 --output json --no-input \
+  --input '{"condition": {"and": [{"column": "status", "operator": "=", "value": "open"}, {"column": "age", "operator": ">", "value": 30}]}}'
+```
+
+- `--input FILE` reads a JSON or YAML file; the format is inferred from the
+  extension.
+- `--input -` reads stdin; then `--input-format json|yaml` is required.
+- The top level must be a mapping. A bad path, format, or shape fails with exit
+  code 2 and a stable error code.
+
+## Condition specs
+A `condition` field is a mapping:
+- leaf: `{"column": ..., "operator": ..., "value": ...}` (plus optional
+  `case_sensitive`, `value_is_column`, `component`, `truncate`).
+- compound: `{"and": [spec, ...]}` or `{"or": [spec, ...]}`.
+- negation: `{"not": spec}`.

mammoth_cli/bundled_skill/mammoth-cli/references/jobs-drafts.md

@@ -0,0 +1,35 @@
+# Jobs, draft mode, and bulk replace
+
+## Jobs
+A command's `wait_policy` (visible via `mammoth schema get`) determines what
+happens with the job, so you do not have to guess:
+
+- `always_wait` and `start_or_wait` commands resolve the job for you and return
+  the final result. You do NOT wait manually.
+- Only a `returns_job` command normally needs you to wait on the job id
+  explicitly:
+  ```bash
+  mammoth job wait 55123 --output json --no-input
+  mammoth job get 55123 --output json --no-input
+  ```
+
+A timeout returns exit code 7 with `recovery_commands` in the envelope that
+re-wait or fetch the job — run those commands. The `--job-timeout` /
+`--pipeline-timeout` options bound the wait.
+
+## Draft mode
+Batch several pipeline edits, then submit them together:
+```bash
+mammoth view draft enter 1039 --project 180 --output json --no-input
+mammoth view transform add-column 1039 --project 180 --output json --no-input \
+  --input '{"name": "flag", "column_type": "TEXT"}'
+mammoth view draft status 1039 --project 180 --output json --no-input
+mammoth view draft submit 1039 --project 180 --output json --no-input
+# or discard the batch
+mammoth view draft discard 1039 --project 180 --output json --no-input --yes
+```
+Draft state is server-side, so it persists across separate CLI processes.
+
+## Bulk replace
+Bulk replace is a reversible pipeline mutation; it needs no `--yes`. Preview or
+re-run through the pipeline commands rather than simulating a dry run.

mammoth_cli/bundled_skill/mammoth-cli/references/machine-output.md

@@ -0,0 +1,30 @@
+# Machine output and exit codes
+
+## Success envelope (stdout)
+```json
+{"schema_version": 1, "data": <result>, "meta": {"command": "project list", "profile": "default", "workspace_id": 4, "project_id": 180, "pagination": null}}
+```
+
+## Error envelope (stderr)
+```json
+{"schema_version": 1, "error": {"code": "resource_not_found", "message": "...", "hint": "...", "details": {}, "request_id": null, "retryable": false, "authorization_required": false, "recovery_commands": ["..."]}}
+```
+
+## Output modes
+`--output` accepts `table` (default, human), `json`, `yaml`, `ndjson`, `plain`.
+Agents should use `json` (or `ndjson` for streams). Machine modes never emit
+color or progress.
+
+## Exit codes
+| code | meaning |
+|---|---|
+| 0 | success |
+| 1 | API error |
+| 2 | usage / input / confirmation failure |
+| 4 | authentication failure |
+| 5 | not found |
+| 6 | conflict |
+| 7 | retryable (network/timeout) |
+| 130 | interrupted |
+
+Branch on the exit code and the stable `error.code`; never parse the message.

mammoth_cli/bundled_skill/mammoth-cli/references/recovery.md

@@ -0,0 +1,28 @@
+# Error recovery and cleanup
+
+## Recover from an error
+Every error envelope carries `error.recovery_commands`: an ordered list of exact
+commands to run next. Prefer them over improvising.
+
+| exit | error.code (examples) | next step |
+|---|---|---|
+| 4 | not_authenticated, authentication_failed | `mammoth auth login` |
+| 5 | resource_not_found | re-list to find the correct id |
+| 2 | project_required | `mammoth context project use ID` or `--project` |
+| 2 | confirmation_required | re-run with `--yes` (and `--confirm TARGET`) |
+| 7 | retryable_error, timeout | wait, then re-run the recovery command |
+
+## Cleanup discipline
+In a shared project, delete only the resources you created, and never touch
+pre-existing ones. Track ids you create and remove them when done:
+```bash
+mammoth dataset delete "$DS" --project 180 --output json --no-input --yes
+mammoth folder delete "$F" --project 180 --output json --no-input --yes
+```
+
+## Discovery when stuck
+```bash
+mammoth capability get GetProjectCheckpoints --output json --no-input
+mammoth schema get view.transform.pivot --output json --no-input
+mammoth doctor --output json --no-input
+```

mammoth_cli/bundled_skill/mammoth-cli/references/safety.md

@@ -0,0 +1,26 @@
+# Safe mutation
+
+Each command carries a reviewed confirmation policy:
+
+| policy | how to satisfy it noninteractively |
+|---|---|
+| none | nothing required |
+| prompt_or_yes | pass `--yes` |
+| yes_always | pass `--yes` (always, even at a terminal) |
+| confirm_target | pass `--yes` and `--confirm TARGET` (exact match) |
+
+Under `--no-input` (and in `json`/`ndjson` modes) there is no prompt: a missing
+`--yes`/`--confirm` fails with exit code 2 and error code
+`confirmation_required` or `confirmation_target_mismatch`.
+
+```bash
+# normal delete
+mammoth folder delete 7 --project 180 --output json --no-input --yes
+
+# high-impact: target must equal the resource
+mammoth project user remove --project 180 --output json --no-input \
+  --yes --confirm 180 --input '{"user_ids": ["u_123"]}'
+```
+
+Discover a command's policy with `mammoth schema get <command.id> --output json`.
+Never retry a mutation blindly; only retry on exit code 7 (retryable).

mammoth_cli/commands/__init__.py

@@ -0,0 +1,29 @@
+"""commands layer for the Mammoth CLI.
+
+Assembles :data:`BESPOKE`: fully-typed Typer command callbacks that override
+the generic manifest leaf for the command ids they implement. ``app.py``
+imports this module and swaps in a bespoke callback wherever one exists,
+registering it at the exact same manifest path and name as the generic leaf
+it replaces.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from mammoth_cli.commands import auth as auth_cmd
+from mammoth_cli.commands import config as config_cmd
+from mammoth_cli.commands import context as context_cmd
+
+BESPOKE: dict[str, Callable[..., None]] = {
+    "auth.login": auth_cmd.auth_login,
+    "auth.status": auth_cmd.auth_status,
+    "auth.logout": auth_cmd.auth_logout,
+    "config.get": config_cmd.config_get,
+    "config.set": config_cmd.config_set,
+    "config.list": config_cmd.config_list,
+    "config.path": config_cmd.config_path,
+    "context.project.status": context_cmd.context_project_status,
+    "context.project.use": context_cmd.context_project_use,
+    "context.project.clear": context_cmd.context_project_clear,
+}

mammoth_cli/commands/activity.py

@@ -0,0 +1,123 @@
+"""Handlers for the ``activity`` command family (workspace-scoped).
+
+Activity logs belong to the authenticated workspace; the SDK client already
+carries the workspace id, so handlers never forward it explicitly. Both
+commands are read-only: ``list`` returns a page of log entries and ``export``
+kicks off a workspace export job. All filters are optional and forwarded only
+when present in the strict ``--input`` document. Handlers dispatch 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``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import CODE_SDK_SYMBOL_UNRESOLVED, EXIT_USAGE, CliError
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service, resolved_project
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+_LIST_OPTIONAL = (
+    "limit",
+    "offset",
+    "sort",
+    "project_id",
+    "categories",
+    "activities",
+    "resource_id",
+    "result",
+    "start_time",
+    "end_time",
+    "origin",
+    "user_ids",
+    "parent_id",
+    "search_text",
+)
+
+_EXPORT_OPTIONAL = (
+    "format",
+    "start_time",
+    "end_time",
+    "categories",
+    "activities",
+    "user_ids",
+)
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The dotted SDK symbol recorded in the command manifest.
+
+    Raises:
+        CliError: ``sdk_symbol_unresolved`` when the manifest has no symbol
+            for this command.
+    """
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy each present field from ``document`` into ``kwargs`` unchanged.
+
+    Args:
+        document: The parsed ``--input`` document.
+        kwargs: The keyword-argument mapping being built for the SDK call.
+        fields: The optional field names to forward when present.
+    """
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int, project_id: int | None) -> dict[str, Any]:
+    """Build the common envelope metadata for an activity command.
+
+    Args:
+        invocation: The current command's resolved global options.
+        workspace_id: The authenticated workspace id.
+        project_id: The active project id, or None when not resolved.
+
+    Returns:
+        The envelope metadata mapping.
+    """
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": project_id,
+    }
+
+
+def activity_list(invocation: Invocation) -> HandlerResult:
+    """List activity logs in the active workspace, with optional filters."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, _LIST_OPTIONAL)
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def activity_export(invocation: Invocation) -> HandlerResult:
+    """Export activity logs from the active workspace, with optional filters."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, _EXPORT_OPTIONAL)
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))

mammoth_cli/commands/addon.py

@@ -0,0 +1,173 @@
+"""Handlers for the ``addon`` command family.
+
+None of these commands are project-scoped: every mutation acts on the
+workspace's addon set (connector addons, storage, and user seats) resolved
+from the caller's credentials. ``addon list`` is a plain read. Every mutation
+is ``high_impact`` and requires ``--yes --confirm WORKSPACE_ID``, enforced
+against the authenticated ``auth.workspace_id`` after the service is opened
+(mirroring ``project.py``'s ``project_bulk_update`` and ``workspace.py``'s
+``workspace_update``). All request fields come from the strict ``--input``
+document; none of these commands take a positional argument. Handlers
+dispatch 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``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    CODE_MISSING_FIELD,
+    CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.confirm import POLICY_CONFIRM_TARGET, enforce_confirmation
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command."""
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _require_field(document: dict[str, Any] | None, field: str) -> Any:
+    """Return a required field from the ``--input`` document, or raise usage."""
+    if document is None or field not in document:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message=f"This command requires the '{field}' input field.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass it via --input, for example: --input '{{\"{field}\": ...}}'.",
+        )
+    return document[field]
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy each present field from ``document`` into ``kwargs`` under the same name."""
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int) -> dict[str, Any]:
+    """Build the common envelope metadata for an addon command (no project scope)."""
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": None,
+    }
+
+
+def addon_connector_add(invocation: Invocation) -> HandlerResult:
+    """Add one or more connector addons. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("connector_id", "connector_ids"))
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"add connector addon(s) to workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_connector_remove(invocation: Invocation) -> HandlerResult:
+    """Remove one or more connector addons. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("connector_id", "connector_ids"))
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"remove connector addon(s) from workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_list(invocation: Invocation) -> HandlerResult:
+    """List active addons for the workspace."""
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation))
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_storage_add(invocation: Invocation) -> HandlerResult:
+    """Add storage capacity. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input()
+    additional_storage_gb = _require_field(document, "additional_storage_gb")
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"add storage to workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), additional_storage_gb=additional_storage_gb)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_storage_remove(invocation: Invocation) -> HandlerResult:
+    """Remove storage capacity. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input()
+    removal_storage_gb = _require_field(document, "removal_storage_gb")
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"remove storage from workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), removal_storage_gb=removal_storage_gb)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_user_add(invocation: Invocation) -> HandlerResult:
+    """Add user seats. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("user_count",))
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"add user seats to workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def addon_user_remove(invocation: Invocation) -> HandlerResult:
+    """Remove user seats. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    document = invocation.load_input()
+    user_count = _require_field(document, "user_count")
+    with open_service(invocation) as (service, auth):
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"remove user seats from workspace {auth.workspace_id}",
+            target=str(auth.workspace_id),
+        )
+        data = service.call(_symbol(invocation), user_count=user_count)
+    return data, _meta(invocation, auth.workspace_id)