mammoth-cli 2.0.0__tar.gz → 2.0.2__tar.gz

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.0
+Version: 2.0.2
 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.2
+Requires-Dist: mammoth-io<0.8,>=0.7.3
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6
@@ -53,10 +53,10 @@ for current row-level coverage and evidence status.
 
 ## Install
 
-Install the 2.0.0 CLI without a preinstalled Python tool manager:
+Install the CLI without a preinstalled Python tool manager:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash -s -- --version 2.0.0 --noninteractive
+curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
 ```
 
 Open a new shell if needed so the installer-added tool directory is on PATH,
@@ -67,9 +67,11 @@ mammoth --version
 mammoth doctor          # checks config, credentials, endpoint, connectivity
 ```
 
-The installer bootstraps its pinned `uv` tool environment when needed. See
-[docs/installation.md](docs/installation.md) for the installer contract and
-the SDK-only pip installation path.
+The installer bootstraps its own `uv` tool environment when needed and installs
+the bundled agent skill. For an exact, reproducible release use `--version
+X.Y.Z`; the installer has no normal prompts. See
+[Installation](docs/installation.md) for that option and the SDK-only pip
+installation path.
 
 ## Quick start
 
@@ -137,26 +139,26 @@ The sample path and project ID are placeholders for a local workbook and a
 project you have resolved and are authorized to modify.
 
 The one-line installer already set up the bundled agent skill for Claude Code,
-Codex, and Cursor. If you installed with `uv`, `pipx`, or `pip` instead:
+Codex, and Cursor. To repair or refresh the installed copy:
 
 ```bash
 mammoth skill install
 ```
 
-See [docs/agents.md](docs/agents.md) and the
-[agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md).
+Start with [Agent handover and operation](docs/agents.md), then load the
+[bundled agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) from the
+installed CLI. The skill routes a task to only the relevant recipe or command
+catalog section; it does not require an agent to absorb the whole reference.
 
 For a fresh external shell agent, start with the shipped
 [portable task-start playbook](mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md).
 
-For an unattended task, use the open-ended loop documented in
-[Agent and CI usage](docs/agents.md): discover a capability and its schema,
-resolve every resource in its explicit scope, compose operations from the IDs
-returned by reads, verify the requested outcome, then recover or clean up from
-the observed state. Examples in this repository are nonexhaustive. The CLI
-never requires an agent to use backend column identifiers: inputs name columns
-by their display names. Do not infer a usable default view from a dataset; run
-`view list DATASET_ID` and choose a view explicitly.
+For an unattended task, use the handover loop: discover its schema, resolve
+every resource in explicit scope, operate from IDs returned by reads, verify
+the requested outcome, then record a nonsecret checkpoint. Examples in this
+repository are nonexhaustive. The CLI never requires backend column identifiers:
+inputs name columns by their display names. Do not infer a usable default view
+from a dataset; run `view list DATASET_ID` and choose a view explicitly.
 
 If another agent must continue the work, write the nonsecret checkpoint format
 described in [Portable agent handoff](docs/agent-handoff.md). It records scope,
@@ -204,7 +206,9 @@ The full generated list is in [docs/reference/commands.md](docs/reference/comman
 | [Installation](docs/installation.md) | Install the CLI and the agent skill. |
 | [Quick start](docs/quickstart.md) | Log in and run your first commands. |
 | [Authentication](docs/authentication.md) | Getting an API key, login, profiles, projects. |
-| [Agent and CI usage](docs/agents.md) | Machine output, structured input, patterns. |
+| [Agent handover and operation](docs/agents.md) | Cold start, discovery, checkpoints, recovery. |
+| [Portable handoff format](docs/agent-handoff.md) | Nonsecret checkpoint schema and receiving procedure. |
+| [Bundled agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) | Focused routing for shell-capable agents. |
 | [Safe mutation](docs/safety.md) | Mutation classes and confirmation policies. |
 | [Output and errors](docs/reference/output-and-errors.md) | Envelopes, exit codes, error codes. |
 | [Global flags](docs/reference/global-flags.md) | The flags every command shares. |
@@ -213,8 +217,8 @@ The full generated list is in [docs/reference/commands.md](docs/reference/comman
 | [Command reference](docs/reference/commands.md) | Every command, grouped by family. |
 
 Start with **Quick start** for a copy-paste workflow, **Authentication** for
-profiles and non-interactive login, or **Agent and CI usage** for schema-driven
-automation. The command reference is generated; use `mammoth schema get
+profiles and non-interactive login, or **Agent handover and operation** for a
+fresh-agent task. The command reference is generated; use `mammoth schema get
 COMMAND.ID` to verify a request shape against the installed CLI.
 
 Agent-readable indexes: [`docs/llms.txt`](docs/llms.txt) and
@@ -272,7 +276,7 @@ Use the [canonical matrix](docs/release-capability-matrix.md) for the full
 
 ## Compatibility
 
-`mammoth-cli` follows [Semantic Versioning](https://semver.org) for the 1.x
+`mammoth-cli` follows [Semantic Versioning](https://semver.org) for the 2.x
 series:
 
 - The machine-output and error-envelope contract is stable. `SCHEMA_VERSION`

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/README.md

@@ -25,10 +25,10 @@ for current row-level coverage and evidence status.
 
 ## Install
 
-Install the 2.0.0 CLI without a preinstalled Python tool manager:
+Install the CLI without a preinstalled Python tool manager:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash -s -- --version 2.0.0 --noninteractive
+curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
 ```
 
 Open a new shell if needed so the installer-added tool directory is on PATH,
@@ -39,9 +39,11 @@ mammoth --version
 mammoth doctor          # checks config, credentials, endpoint, connectivity
 ```
 
-The installer bootstraps its pinned `uv` tool environment when needed. See
-[docs/installation.md](docs/installation.md) for the installer contract and
-the SDK-only pip installation path.
+The installer bootstraps its own `uv` tool environment when needed and installs
+the bundled agent skill. For an exact, reproducible release use `--version
+X.Y.Z`; the installer has no normal prompts. See
+[Installation](docs/installation.md) for that option and the SDK-only pip
+installation path.
 
 ## Quick start
 
@@ -109,26 +111,26 @@ The sample path and project ID are placeholders for a local workbook and a
 project you have resolved and are authorized to modify.
 
 The one-line installer already set up the bundled agent skill for Claude Code,
-Codex, and Cursor. If you installed with `uv`, `pipx`, or `pip` instead:
+Codex, and Cursor. To repair or refresh the installed copy:
 
 ```bash
 mammoth skill install
 ```
 
-See [docs/agents.md](docs/agents.md) and the
-[agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md).
+Start with [Agent handover and operation](docs/agents.md), then load the
+[bundled agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) from the
+installed CLI. The skill routes a task to only the relevant recipe or command
+catalog section; it does not require an agent to absorb the whole reference.
 
 For a fresh external shell agent, start with the shipped
 [portable task-start playbook](mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md).
 
-For an unattended task, use the open-ended loop documented in
-[Agent and CI usage](docs/agents.md): discover a capability and its schema,
-resolve every resource in its explicit scope, compose operations from the IDs
-returned by reads, verify the requested outcome, then recover or clean up from
-the observed state. Examples in this repository are nonexhaustive. The CLI
-never requires an agent to use backend column identifiers: inputs name columns
-by their display names. Do not infer a usable default view from a dataset; run
-`view list DATASET_ID` and choose a view explicitly.
+For an unattended task, use the handover loop: discover its schema, resolve
+every resource in explicit scope, operate from IDs returned by reads, verify
+the requested outcome, then record a nonsecret checkpoint. Examples in this
+repository are nonexhaustive. The CLI never requires backend column identifiers:
+inputs name columns by their display names. Do not infer a usable default view
+from a dataset; run `view list DATASET_ID` and choose a view explicitly.
 
 If another agent must continue the work, write the nonsecret checkpoint format
 described in [Portable agent handoff](docs/agent-handoff.md). It records scope,
@@ -176,7 +178,9 @@ The full generated list is in [docs/reference/commands.md](docs/reference/comman
 | [Installation](docs/installation.md) | Install the CLI and the agent skill. |
 | [Quick start](docs/quickstart.md) | Log in and run your first commands. |
 | [Authentication](docs/authentication.md) | Getting an API key, login, profiles, projects. |
-| [Agent and CI usage](docs/agents.md) | Machine output, structured input, patterns. |
+| [Agent handover and operation](docs/agents.md) | Cold start, discovery, checkpoints, recovery. |
+| [Portable handoff format](docs/agent-handoff.md) | Nonsecret checkpoint schema and receiving procedure. |
+| [Bundled agent skill](mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) | Focused routing for shell-capable agents. |
 | [Safe mutation](docs/safety.md) | Mutation classes and confirmation policies. |
 | [Output and errors](docs/reference/output-and-errors.md) | Envelopes, exit codes, error codes. |
 | [Global flags](docs/reference/global-flags.md) | The flags every command shares. |
@@ -185,8 +189,8 @@ The full generated list is in [docs/reference/commands.md](docs/reference/comman
 | [Command reference](docs/reference/commands.md) | Every command, grouped by family. |
 
 Start with **Quick start** for a copy-paste workflow, **Authentication** for
-profiles and non-interactive login, or **Agent and CI usage** for schema-driven
-automation. The command reference is generated; use `mammoth schema get
+profiles and non-interactive login, or **Agent handover and operation** for a
+fresh-agent task. The command reference is generated; use `mammoth schema get
 COMMAND.ID` to verify a request shape against the installed CLI.
 
 Agent-readable indexes: [`docs/llms.txt`](docs/llms.txt) and
@@ -244,7 +248,7 @@ Use the [canonical matrix](docs/release-capability-matrix.md) for the full
 
 ## Compatibility
 
-`mammoth-cli` follows [Semantic Versioning](https://semver.org) for the 1.x
+`mammoth-cli` follows [Semantic Versioning](https://semver.org) for the 2.x
 series:
 
 - The machine-output and error-envelope contract is stable. `SCHEMA_VERSION`

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

mammoth_cli-2.0.2/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mammoth-cli
+description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines, dashboards, exports, and handoffs."
+---
+
+# Mammoth CLI
+
+Use this skill for Mammoth shell work, not for Python SDK integration. Start
+with the installed command contract rather than guessed routes or payloads:
+
+```bash
+mammoth schema find "TASK OR RESOURCE" --output json --no-input
+mammoth schema get COMMAND_ID --output json --no-input
+```
+
+`schema list` is the complete CLI inventory. `capability list` is an
+API-binding inventory and can omit typed/local CLI routes. Use deterministic
+JSON (`--output json --no-input`) whenever another program or agent consumes
+the result.
+
+## Working rules
+
+- Resolve workspace/project/dataset/view parents from reads; pass observed IDs
+  and `--project`. A dataset does not select a default view.
+- Use exact view-schema **display names** in expressions and column inputs,
+  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.
+- 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.
+
+## Route only what the task needs
+
+- **Cold start, task plan, or unsupported route:** [task start](references/task-start.md)
+- **Login, profiles, and authorized scope:** [auth](references/auth.md)
+- **Nested input, output envelopes, confirmations, jobs, or recovery:**
+  [input](references/input.md), [machine output](references/machine-output.md),
+  [safety](references/safety.md), [jobs and drafts](references/jobs-drafts.md),
+  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)
+- **Pause or transfer to another agent:** [handoff](references/handoff.md)
+
+## Handoff checklist
+
+Before yielding work, write a nonsecret checkpoint with the intent and
+acceptance criteria; authorized profile/workspace/project; observed resource
+parents; verified evidence hashes; known jobs and unknown outcomes; remaining
+objectives; and exact cleanup ownership. The receiving agent validates that
+record and re-reads remote state before deciding what to do next. The handoff
+is not a resume command or a grant of authority.

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/mammoth_cli/bundled_skill/mammoth-cli/references/machine-output.md

@@ -15,18 +15,14 @@
 These are compact shapes, not substitutes for `schema get`. IDs and field
 names must come from the preceding read/create response.
 
-The following are abbreviated from retained CLI 1.1.5 evidence, with values
-reduced only for brevity. They show envelope keys, not a universal result
-schema. Dashboard and transform result fields remain schema-driven.
+The following are illustrative envelope shapes. They show keys, not a universal
+result schema; dashboard and transform result fields remain schema-driven.
 
 ```json
 {"schema_version":1,"data":{"id":5,"ds_id":5,"name":"View 1","row_count":51,"status":"ready","metadata":[{"display_name":"store_id","internal_name":"column_1","type":"TEXT"}]},"meta":{"command":"view get","pagination":null,"profile":"expanded-live","project_id":null,"workspace_id":4}}
 {"schema_version":1,"data":{"output_path":"dataview_12_12_export.csv"},"meta":{"command":"view export csv","pagination":null,"profile":"expanded-live","project_id":null,"workspace_id":4}}
 ```
 
-Sources: `docs/live-evidence-20260917/transform-next/view-get.json` and
-`docs/live-evidence-20260917/export-next/export-csv.json` (CLI 1.1.5).
-
 For pagination, preserve the returned `meta.pagination`/`data.next` cursor and
 request the next page only with fields accepted by that command's schema. For
 auth, `auth status` reports profile/endpoint/workspace state but never a

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -11,23 +11,17 @@ profile in that shell. If the broker/sidecar is not provided, stop before any
 authenticated action. The profile workflow below remains for ordinary,
 non-evaluated operator use.
 
-1. Check whether `mammoth` is available. If it is absent, create and activate a
-   dedicated virtual environment, then install either the exact wheel file
-   authorized by the task/release record or an actually published pinned
-   release:
+1. Check whether `mammoth` is available. If it is absent, install the CLI and
+   bundled skill with the supported host installer:
 
    ```bash
-   python -m venv .mammoth-cli-env
-   . .mammoth-cli-env/bin/activate
-   python -m pip install "/path/to/authorized/mammoth_cli-PINNED_VERSION-py3-none-any.whl"
-   # Or, only when that exact release is published and authorized:
-   python -m pip install "mammoth-cli==PINNED_VERSION"
+   curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
    ```
 
-   Replace `PINNED_VERSION` and the wheel path only with authorized values; do
-   not install an unpinned latest version. If a SHA-256 is supplied with the
-   authorized wheel, verify it before installation (for example with
-   `sha256sum`) and stop on mismatch. Then run `mammoth --version`.
+   For an evaluation or deployment that names an exact approved release, append
+   `--version X.Y.Z`. Verify the installed result with `mammoth --version`.
+   Do not substitute a manual pip/uv install for this
+   CLI path; Python applications install the SDK separately.
 2. Locate the installed guidance with `mammoth skill path --output json
    --no-input` and read the canonical skill plus its references. If a skill
    install is required for the agent host, run `mammoth skill install

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/mammoth_cli/commands/schema.py

@@ -738,7 +738,7 @@ def _schema_common(record: dict[str, Any]) -> dict[str, Any]:
         # not returned by an API. Preserve JSON-Schema declaration names (for
         # example ``properties.api_secret``) through Result/render's second
         # normalization pass without trusting arbitrary result dictionary keys.
-        input_schema = trusted_json_schema(input_schema)
+        input_schema = cast(dict[str, Any], trusted_json_schema(input_schema))
     contract = _compact_contract(record)
     opaque_fields = [
         str(field["name"])

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/mammoth_cli/commands/view_ops.py

@@ -110,7 +110,9 @@ def _resolve_exact_dataset_id(
         if effective_project is not None and resource.project_id != effective_project:
             raise CliError(
                 code="invalid_resource_context",
-                message="The resource reference project does not match the effective project scope.",
+                message=(
+                    "The resource reference project does not match the effective project scope."
+                ),
                 exit_status=EXIT_USAGE,
             )
     raw_values = [

{mammoth_cli-2.0.0 → mammoth_cli-2.0.2}/pyproject.toml

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

mammoth_cli-2.0.0/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,49 +0,0 @@
----
-name: mammoth-cli
-description: "Operate Mammoth Analytics with the published CLI: authenticate, discover contracts, manage projects/data/views/pipelines/dashboards, and verify safe mutations."
----
-
-# Mammoth CLI
-
-Use deterministic JSON: `mammoth … --output json --no-input`. Discover before
-mutating: `mammoth schema get COMMAND_ID` gives exact fields; inspect the JSON
-success/error envelope and `recovery_commands`, never guess an alias or replay
-an `outcome_unknown` mutation. Read back results and delete only IDs returned
-by this task.
-
-Resolve project/dataset/view parents from reads and pass the observed scope.
-For columns and expressions use exact view-schema **display names**, never
-backend aliases. A timeout or unknown mutation outcome requires reconciliation
-of the specific target before any retry.
-
-Start cold tasks with [task-start](references/task-start.md). For credentials,
-scope, machine output, structured input, confirmations, jobs and recovery use
-[auth](references/auth.md), [machine output](references/machine-output.md),
-[input](references/input.md), [safety](references/safety.md),
-[jobs/drafts](references/jobs-drafts.md), and [recovery](references/recovery.md).
-In an evaluated worker, use a controller-provided auth broker; do not mount or
-read a credential profile.
-
-Before creating or cleaning resources, classify them with [retention and
-cleanup](references/retention.md). Preserve requested datasets, views,
-dashboards, and export artifacts; cleanup requires explicit exact-ID
-authorization and never means delete-all-owned-resources.
-
-For data work—including transforms, blend/task/pipeline drafts, dashboards and
-exports—read [operations](references/operations.md). For every published CLI
-command, load only the relevant domain from the generated
-[command catalog](references/command-index.md): it provides the command path,
-schema ID, compact example, expected result type, mutation/confirmation/wait
-policy, and error/recovery pointer. The catalog covers local CLI manifest
-commands; `capability list` is an API-binding inventory, not a complete list
-of typed/local CLI routes. Use the catalog plus `schema list/find/get` to
-discover CLI support, then use capability metadata only for its API-binding
-and evidence boundary.
-
-For focused end-to-end patterns—uploads and URL imports, resource navigation,
-typed transforms, dashboards, exports, and owned cleanup—read the
-[recipes index](references/recipes/index.md).
-
-For a safe cross-agent continuation, read the nonsecret [handoff
-format](references/handoff.md). It records scope, observed IDs, jobs, unknown
-outcomes, and cleanup ownership; it never transfers credentials or authority.