Metadata-Version: 2.4
Name: mammoth-cli
Version: 2.2.82
Summary: Command-line interface for the Mammoth Analytics platform
Project-URL: homepage, https://mammoth.io
Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
Project-URL: documentation, https://docs.mammoth.io/build/cli
Author-email: Mammoth Analytics <support@mammoth.io>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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.42
Requires-Dist: platformdirs<5,>=4.10
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<16,>=15
Requires-Dist: tomlkit<0.16,>=0.15.1
Requires-Dist: typer<0.28,>=0.27
Description-Content-Type: text/markdown

# mammoth-cli

Use [Mammoth Analytics](https://mammoth.io) from a terminal. The `mammoth`
command covers data import and export, transformations, project organization,
automation, and administration. Its interface is readable at a
shell and predictable in scripts and agent runs.

[![PyPI](https://img.shields.io/pypi/v/mammoth-cli)](https://pypi.org/project/mammoth-cli/)
[![Python](https://img.shields.io/pypi/pyversions/mammoth-cli)](https://pypi.org/project/mammoth-cli/)
[![License](https://img.shields.io/pypi/l/mammoth-cli)](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/LICENSE)

- **Human-friendly by default.** In a terminal, commands print a readable table.
- **Agent-native.** When you pipe the output, you get a stable JSON envelope with a
  documented schema, exit codes, and error codes — no flags required.
- **Guarded mutations.** Commands expose their confirmation policy; promptless
  destructive operations require an explicit `--yes`.
- **Discoverable.** `mammoth capability list` and `mammoth schema get` describe
  every command, so an agent can learn the surface at runtime.

The CLI uses the public [`mammoth-io`](https://pypi.org/project/mammoth-io/)
SDK. It adds no second HTTP client and calls no private SDK members.

See the [capability matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.md)
for current row-level coverage and evidence status.

## Install

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
```

Open a new shell if needed so the installer-added tool directory is on PATH,
then confirm it works:

```bash
mammoth --version
```

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` (a pinned install is not auto-updated); the installer has no normal prompts. See
[Installation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/installation.md) for that option and the SDK-only pip
installation path.

## First run: authenticate, check, then discover

Authentication is the first operational step. Check the selected profile;
this is a local presence check, not a live access test. If the profile or
stored credentials are absent, log in before running `doctor` or any data
command. An agent does this by asking the operator to run the login below in
their own terminal; the CLI never reads credentials from environment variables:

```bash
mammoth skill show
# Read the SKILL.md it prints before operating; `mammoth skill agents-md install`
# writes a short steering block into AGENTS.md so future sessions start here.
mammoth auth status
# Compare the reported endpoint with the intended target before doctor.
# Use app for production; use release only when explicitly intended.
# Human terminal only, if profile or stored credentials are absent:
mammoth auth login
# Then verify configuration, credentials, endpoint, and connectivity:
mammoth doctor
# Then discover a task-specific route:
mammoth schema find "TASK OR RESOURCE"
mammoth schema get COMMAND_ID
# Optional API-binding inventory (not the complete CLI surface):
mammoth capability list
```

For an agent or CI, do not request or paste secrets into chat, prompts, shell
history, or command arguments. On POSIX, put the required JSON credentials in a
private owner-only (0600) file outside the repository and pass its path to:

```bash
mammoth auth login --input /private/path/credentials.json --storage file
```

On Windows, use the approved OS keyring instead; do not use a file fallback
unless its ACL hardening is approved, and stop if it is not available.

The default server prefix is `app`; pass `--server-prefix release` only when
the release endpoint is explicitly intended. Compare the endpoint reported by
`auth status` with the intended target before running `doctor`; if it does not
match, stop and switch to a separate correctly configured profile. See
[Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md)
for the required JSON fields and profile behavior. After `doctor` succeeds,
resolve the exact workspace, project, dataset, and view from read results
before operating; verify every mutation. Use `schema find`/`schema get` for
typed and local CLI routes; `capability list` is only an API-binding inventory
and may omit them. Full walkthrough:
[docs/quickstart.md](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/quickstart.md).

## Built for agents and CI

Piping or redirecting output yields the machine envelope, and `--no-input` turns
on automatically off a terminal, so an agent needs no special flags:

```bash
mammoth project list | jq '.data'
```

To pin it for a whole session, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1`
(a flag still wins). Log in without a prompt with
the private, permission-checked file described above:

```bash
mammoth auth login --input /private/path/credentials.json --storage file
```

Feed multi-field requests as one document instead of many flags:

```bash
mammoth view transform math 1039 --project 180 \
  --input '{"expression": "Unit Price * Quantity", "new_column": "Revenue"}'
```

For pipeline transformations, prefer the typed commands and inspect their
schemas before composing input. For example:

```bash
mammoth schema get view.transform.filter
mammoth schema get view.transform.math
mammoth schema get view.transform.substring
```

The generic `view task add`, `view task preview`, and `view task update`
commands are low-level expert routes. Their `task_spec` object is intentionally
opaque in the installed schema; use a typed `view transform` command instead
of inventing task fields. High-impact imports must also identify and confirm
their target explicitly, for example:

```bash
mammoth dashboard import-workbook ./sample.twbx --project 456 \
  --yes --confirm 456
```

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. To repair or refresh the installed copy:

```bash
mammoth skill install
```

Start with [Agent handover and operation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agents.md), then load the
[bundled agent skill](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/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](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md).

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](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-handoff.md). It records scope,
intent, verified evidence, jobs/unknown outcomes, and cleanup ownership without
putting credentials into the handoff.

## Give your coding agent the CLI playbook

The shortest handover is a prompt. Fill `PROJECT NAME` and `TASK` and paste
it into any agent with a bash tool; it installs the CLI, walks you through the
one-time login, and works from the shipped skill. The long form is
[docs/agent-prompt.md](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-prompt.md).

```text
Use Mammoth Analytics only through the `mammoth` CLI in bash, never the web
app in a browser; run `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
Onboard me first:
1. If `mammoth --version` fails, install, then re-check (new shell if needed):
   curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
2. Run `mammoth auth status`. If it shows no credentials or a
   `recommendation`, print exactly this and wait until I say done: "In the
   Mammoth web app open Workspace settings → API Tokens → Create token (no
   project, so I can create projects), copy the token (it starts with mm_ and
   is shown once), then run in your own terminal: mammoth auth login". Or run
   `mammoth auth login --device` yourself, show me the link and code it prints and wait
   for it to finish — never ask for, read, or pass the token yourself, and never run any
   other auth login method.
3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
   follow the guide it prints.
Work inside `mammoth project ensure 'PROJECT NAME'` unless I name a project;
take ids only from reads; find a command with `schema find "GOAL IN PLAIN
WORDS"` or `view transform --help`, and `schema get COMMAND_ID` before a new
command; read results back before reporting.
TASK: <what to achieve, and how you will know it is done>
```

The bundled skill describes authentication, discovery, structured input, job
handling, and confirmations. Install it for the supported coding-agent tools:

```bash
mammoth skill install
mammoth skill list
```

The default target is user scope. To inspect destinations before writing, run
`mammoth skill path`. To install only for one agent in the current project, use
structured input:

```bash
mammoth skill install --input '{"agents": ["codex"], "scope": "project"}'
```

Use `mammoth skill update` after a CLI upgrade. It refreshes copies owned by the
installer and reports modified copies instead of silently replacing them.

In an interactive terminal the CLI keeps itself up to date. At most once a day, after a command has
finished and written its output, a detached process asks PyPI and installs a
newer release through the same package manager as `mammoth upgrade`. It never
delays or fails a command, prints nothing, and writes any failure to the run
log. `meta.update_available` (and the stderr line in human output) appears only
when a newer release exists and will not be installed by itself (auto-update off,
a pinned install, a failed install, or a session that is not interactive). Nothing
is installed in CI (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, ...) or when stdin or
stdout is not a terminal (agents, pipes); the check and the hint still run there.
`MAMMOTH_AUTO_UPGRADE=1` forces the install on anyway, `MAMMOTH_NO_AUTO_UPDATE=1`
keeps the check but never installs, or `MAMMOTH_NO_UPDATE_CHECK=1` to turn the check off (see
[Upgrade](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/upgrade.md)).

## What you can do

| Area | Command families |
|---|---|
| Data in and out | `file`, `dataset`, `connector`, `addon` |
| Shape and analyze | `view`, `dataset`, `ai` |
| Organize | `project`, `folder`, `dashboard`, `report`, `template` |
| Automate | `automation`, `workflow`, `schedule`, `batch`, `webhook` |
| Administer | `workspace`, `user`, `billing`, `client-app`, `external-key` |
| Operate the CLI | `auth`, `context`, `config`, `doctor`, `log`, `capability`, `schema`, `skill`, `upgrade` |

The full generated list is in [docs/reference/commands.md](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/reference/commands.md).

## Documentation

| Guide | What it covers |
|---|---|
| [Installation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/installation.md) | Install the CLI and the agent skill. |
| [Quick start](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/quickstart.md) | Log in and run your first commands. |
| [Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md) | Getting an API token, login, profiles, projects. |
| [Agent handover and operation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agents.md) | Cold start, discovery, checkpoints, recovery. |
| [Portable handoff format](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-handoff.md) | Nonsecret checkpoint schema and receiving procedure. |
| [Bundled agent skill](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) | Focused routing for shell-capable agents. |
| [Safe mutation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/safety.md) | Mutation classes and confirmation policies. |
| [Output and errors](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/reference/output-and-errors.md) | Envelopes, exit codes, error codes. |
| [Global flags](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/reference/global-flags.md) | The flags every command shares. |
| [Troubleshooting](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/troubleshooting.md) | Exit codes, error envelopes, the run log, recovery. |
| [Agent prompt](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-prompt.md) | Paste-ready prompt: an agent uses Mammoth through the CLI in bash. |
| [Upgrade](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/upgrade.md) / [Uninstall](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/uninstall.md) | Keep the CLI current, or remove it. |
| [Command reference](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/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 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`](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/llms.txt) and
[`docs/llms-full.txt`](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/llms-full.txt).

## Production readiness

[`docs/production-readiness.md`](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/production-readiness.md)
is the one-page verdict: what is proven live, what is not, and where every
claim's evidence lives. Read it before promising a deliverable.

## Capability-matrix status

The committed machine-readable release matrix is the canonical repository
inventory; historical readiness records are kept separately from this summary. The
repository-facing summary is
[`docs/agent-capability-coverage.md`](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-capability-coverage.md).
The current release snapshot contains **528 operations across 355 paths** (the
historical pinned M0 snapshot was **445 operations across 287 paths**).
The matrix separates **Core** ETL/workflow capabilities from **Miscellaneous**
surfaces. Its live status counts are intentionally not duplicated here; read
the linked row-level matrix for the current values. It does not declare Full
readiness: matrix rows are planning/review status, not release qualification
or live semantic proof.
No status changes are inferred from an OpenAPI refresh: additions begin
Unassessed and removals or operation-ID changes require review. Use
`scripts/report_release_capability_drift.py --help` to produce a deterministic
local review queue from a candidate OpenAPI JSON; it never implements routes or
promotes support. See the [capability drift workflow](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/capability-drift-workflow.md)
for the required row fields and review steps. No secrets or live evidence are
copied into this README.
The sanitized [row-level release matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.md)
and [machine-readable matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.json) preserve all
528 method/path line items without pilot payloads or credentials.

### Core top-15 snapshot

This compact table is a navigation summary, not a family-wide qualification
claim. The linked matrix row is canonical; `Unassessed` means no support claim.

| Area | Capability | ID | Status | Evidence/limitation |
|---|---|---:|---|---|
| Project | List projects | REL-174 | Partial | One bounded project-list read. |
| Project | Create project | REL-431 | Unassessed | No owned project lifecycle evidence. |
| Project | Update project | REL-286 | Unassessed | No approved lifecycle evidence. |
| Project | Delete project | REL-037 | Unassessed | Protected project scope; no disposable project. |
| Dataset | Create dataset | REL-443 | Partial | Owned disposable create/readback/cleanup evidence. |
| Dataset | List datasets | REL-191 | Partial | Bounded list/readback evidence. |
| Dataset | Get dataset | REL-192 | Partial | One retained-resource read. |
| Dataset | Delete dataset | REL-044 | Partial | Owned delete and absence readback; variants remain untested. |
| View | Create/duplicate view | REL-446 | Partial | One disposable view lifecycle. |
| View | List views | REL-197 | Partial | One retained view/parent scope. |
| View | Get view | REL-198 | Partial | Positive and invalid-parent controls. |
| View | Pipeline task readback | REL-214 | Partial | Typed transforms require schema discovery; bounded task-list evidence. |
| Dashboard | Create dashboard | REL-326 | Unassessed | No current approved create fixture. |
| Dashboard | Get dashboard | REL-107 | Partial | One retained dashboard read. |
| Folder | Get folder | REL-224 | Full | Public CLI 1.1.12 receipt covers fields, filtered list, errors, lifecycle, and final absence; folder family remains incomplete. |

Use the [canonical matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.md) for the full
528-row inventory and exact evidence links.

## Compatibility

`mammoth-cli` follows [Semantic Versioning](https://semver.org) for the 2.x
series:

- The machine-output and error-envelope contract is stable. `SCHEMA_VERSION`
  (see `mammoth_cli/__init__.py`) identifies it and never changes incompatibly
  within a major version. New fields may be added; existing ones are preserved.
- The CLI surface is stable. Command names, flags, and exit codes are not
  removed or repurposed within a major version.
- Bug fixes ship in patch releases. Additive changes ship in minor releases.

## Development

```bash
pytest tests/ -q                 # unit + contract tests (live tests deselected)
ruff check mammoth_cli scripts tests
mypy mammoth_cli
make cli-docs-check              # documentation gates
```

Build scripts under `scripts/` regenerate the manifests and the documentation
corpus offline. Release and packaging details live in
[RELEASING.md](https://github.com/EdgeMetric/mammothsdk/blob/main/RELEASING.md).

## License

See [LICENSE](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/LICENSE). Source: https://github.com/EdgeMetric/mammothsdk
