Skip to content
Documentation: open the docs menu

Mammoth for coding agents

Mammoth Analytics is a data platform: workspaces contain projects, projects contain datasets, and datasets carry one or more views, each a pipeline of transformation steps. The mammoth CLI is the agent interface—it describes itself at runtime, emits a stable JSON envelope, and declares how dangerous every operation is before it runs.

Install

curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | sh
mammoth skill list      # confirm the skill landed

The installer downloads its own pinned copy of uv, so you need no Python tool manager of your own. It checks that the CLI starts and installs the bundled agent skill, which teaches your coding agent the CLI's authentication, discovery, input, and confirmation conventions.

Already using pipx or pip? Install the package, then add the skill yourself:

pipx install mammoth-cli    # or: pip install --no-cache-dir --upgrade mammoth-cli
mammoth skill install
mammoth --version           # check you got the newest release

--no-cache-dir matters right after a release: a cached package index can still hand out the previous version. Once installed, mammoth upgrade moves to the latest release (pass --yes in an agent or CI run, where there is no prompt), and an envelope carrying meta.update_available names the command to run. Auto-update installs only in an interactive terminal; set MAMMOTH_AUTO_UPGRADE=1 to force it in CI or an agent run.

mammoth skill install copies the skill into every agent it knows about at once. The default target is user scope for Claude Code, Codex and Cursor; see the agent skill for project-scoped installs and per-agent targeting.

Alternatively, if your tooling speaks the community skills convention:

npx skills add https://mammoth.io/docs

Authenticate

The CLI takes credentials from four places: a browser or device-code sign-in, a hidden prompt for an API token, an owner-only --input file, or, for CI, the MAMMOTH_API_TOKEN environment variable. The first three save a profile, in the OS keyring (or an explicitly chosen 0600 file on headless POSIX systems), which later commands reuse. The API token (mm_...) comes from Settings → API Keys → Generate key in the web app, and names its own workspace. See API authentication.

With a coding agent, the agent signs in for you with a device code. The bundled skill tells it to:

  1. Run mammoth auth login --device itself when no profile has credentials.
  2. Show you the link and the short code the command prints.
  3. Wait while you approve the sign-in in your browser, and carry on once the command exits.

The skill also tells the agent never to ask you for a token in chat, never to read one from a file or an environment variable, and never to use another sign-in method.

For CI or another fully unattended run, the operator (not the agent) puts the token in the CI secret store and exposes it as MAMMOTH_API_TOKEN:

export MAMMOTH_API_TOKEN="mm_..."        # from your CI secret store
mammoth doctor --output json --no-input

While the variable is set it outranks any saved profile, unless one is named with --profile or MAMMOTH_PROFILE. The alternative is an owner-only (0600) credentials file, created with those permissions from the start rather than chmod-ed afterwards, consumed once with mammoth auth login --input creds.json --storage file --output json --no-input. Agents and CI has both.

doctor is the precondition check: auth, endpoint, connectivity and version. Treat a doctor failure as a reason to stop, not a reason to try the next command anyway.

A prompt to give your agent

Follow https://mammoth.io/docs/agents/. Set up Mammoth in this project.
When you need to sign in, start a device sign-in and show me the link and code. Show me what changed.

Your agent will land on this page, install the CLI and its skill, and start mammoth auth login --device. You open the link it shows you, check the code, and approve in your browser. It never sees a token.

Discover the contract

mammoth schema find "merge two datasets" --output json --no-input   # find the command for a goal; the top matches carry their input fields and an example
mammoth schema list --output json --no-input        # every command, by family
mammoth schema get <command.id> --output json --no-input   # one command in full: input, mutation_class, confirmation
mammoth capability list --output json --no-input   # the Python SDK method and API operation behind each command

A write adds a verify verdict and a fresh state read-back to its result; read them before you report the change as done.

Every result is one JSON envelope on stdout:

{"schema_version": 1, "data": <result>, "meta": {"command": "…"}}

and every failure is one JSON envelope on stderr, with a stable error.code to branch on—never the message text:

{"schema_version": 1, "error": {"code": "…", "message": "…", "hint": "…", "retryable": false, "recovery_commands": ["…"]}}

Full envelope shape, the exit-code table and rate limits live on errors and exit codes, which owns them.

Where things are

  • /build/—the API, CLI and SDK reference, and the generated capability contract
  • /build/cli/—the CLI's command families, one at a time
  • Agent skill—what mammoth skill install puts on disk, and how to target it
  • Use Mammoth with Claude—Claude Code with the CLI, and the docs MCP server in Claude on the web, Claude Desktop, and Claude Code
  • Mammoth MCP server—the hosted server at https://mcp.mammoth.io/mcp for MCP clients that act on a workspace
  • Agents and CI—non-interactive operation: signing in without a terminal, structured input, job handling
  • Blast radius and safety—the mutation classes and confirmation policies every command declares
  • llms.txt—the machine-readable index of this documentation

Docs for machines

Every page on this site has a machine-readable twin: append .md to a doc's URL, or send Accept: text/markdown on the request, to get the same content as plain Markdown instead of the rendered page. https://mammoth.io/docs/llms.txt is the flat index of the docs for a model to read before it fetches anything else; https://mammoth.io/docs/llms-full.txt is the same index with every page's content inline, for a client that would rather read once than crawl. https://mammoth.io/docs/.well-known/skills/index.json lists the skills these docs publish in the community skills discovery format, which is what npx skills add above reads; https://mammoth.io/docs/.well-known/agent-skills/index.json lists the same skill as one archive.

Separately, a documentation-search MCP server runs at https://mammoth.io/docs/mcp/ (server card: https://mammoth.io/docs/.well-known/mcp/server-card.json): three tools—search_docs, get_doc and list_docs—over streamable-HTTP, with no authentication required, so you can look up Mammoth documentation without a Mammoth account. It answers questions about Mammoth; it does not act on a Mammoth workspace. To act on a workspace, use the CLI above, or the Mammoth MCP server at https://mcp.mammoth.io/mcp. Use Mammoth with Claude has the setup for Claude on the web, Claude Desktop, and Claude Code.

To add both MCP servers to Claude Code:

claude mcp add --transport http mammoth https://mcp.mammoth.io/mcp            # acts on your workspace, OAuth sign-in
claude mcp add --transport http mammoth-docs https://mammoth.io/docs/mcp/    # searches these docs, no sign-in

Report an issue · support@mammoth.io