mammoth-cli

Use Mammoth Analytics from a terminal. The mammoth command covers data import and export, transformations, project organization, automation, and administration. Its interface is designed to be readable at a shell and predictable in scripts and agent runs.

• Human-friendly by default. In a terminal, commands print a readable table.
• Agent-native. When output is piped, 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 is built on the public mammoth-io SDK. It adds no second HTTP client and calls no private SDK members.

See the capability matrix for current row-level coverage and evidence status.

Install

Install the CLI without a preinstalled Python tool manager:

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:

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; the installer has no normal prompts. See Installation 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:

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:

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

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:

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:

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

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

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:

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:

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:

mammoth skill install

Start with Agent handover and operation, then load the bundled agent skill 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.

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

Use Mammoth Analytics only through the `mammoth` CLI in bash; 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, print exactly this
   and wait until I say done: "In the Mammoth web app open account settings,
   create an API key (key + secret) and note your workspace id, then run in
   your own terminal: mammoth auth login" — never ask for, read, or pass a key
   or secret yourself, and never run auth login.
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; `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:

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:

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.

The CLI checks PyPI for a newer release at most once a day, after a command has finished: every JSON envelope carries meta.update_available and human output adds one stderr line. Set MAMMOTH_NO_UPDATE_CHECK=1 to turn it off, or MAMMOTH_AUTO_UPGRADE=1 to have it upgrade itself (opt-in; see Upgrade).

What you can do

The full generated list is in docs/reference/commands.md.

Documentation

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 and docs/llms-full.txt.

Production readiness

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. 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 for the required row fields and review steps. No secrets or live evidence are copied into this README. The sanitized row-level release matrix and machine-readable matrix 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.

Use the canonical matrix for the full 528-row inventory and exact evidence links.

Compatibility

mammoth-cli follows Semantic Versioning 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

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.

License

See LICENSE. Source: https://github.com/EdgeMetric/mammothsdk