> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth CLI in agents and CI

> Sign in without a terminal, pass structured input, wait on jobs, read the JSON envelope, and clean up safely. Machine behaviour turns on by itself.

Running the `mammoth` CLI where there is no terminal: credentials, structured input, job handling, and a loop that fails safely.

Machine behaviour is automatic. Piping or redirecting output yields the JSON envelope, and `--no-input` turns on by itself when standard input is not a real terminal. No special flags are required. Passing `--output json --no-input` explicitly anyway is good practice: it makes the intent visible in the log.

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

## Signing in without a terminal

An agent or CI job cannot answer a hidden prompt for a secret. The CLI reads credentials from exactly two places—an explicit `--input` handed to the command, or a previously saved profile—and never from environment variables. For CI, the human operator (not the agent) provisions an owner-only (`0600`) credentials file out of band—created with those permissions from the start, not `chmod`-ed afterwards—and the run consumes it once to create a profile:

```bash
mammoth auth login --input creds.json --storage file --output json --no-input
mammoth doctor --output json --no-input
```

`creds.json` is `{"api_token": "mm_...", "server_prefix": "app"}`, `server_prefix` optional. Create the token in **Workspace settings → API Tokens**; a token limited to one project gets HTTP 403 in every other project, so pass that project with `--project ID`. `--storage file` is explicit on POSIX: `--storage auto` can require an OS keyring that a CI runner does not have.

> **Keep credentials out of arguments and out of chat**
>
> Anything on the command line lands in shell history and CI logs. Use a `0600` file. Secrets never appear in any Mammoth envelope, and an agent must never ask a person to paste one into a conversation.

## Structured input

Pass a multi-field request as one document rather than many flags: a file path, or `-` for stdin with an explicit `--input-format`.

```bash
mammoth view transform math 1039 --project 180 \
  --input '{"expression": "price * qty", "new_column": "total"}'

mammoth <command> --input request.yaml
echo '{"...": "..."}' | mammoth <command> --input - --input-format json
```

## A reliable operation loop

1. Discover the command and its request shape with `mammoth schema get <command.id>`.
2. Run reads with `--output json --no-input` and keep the ids that come back.
3. For a mutation, supply its structured input and the confirmation its policy requires (`--yes`, or `--yes --confirm TARGET`)—see [blast radius and safety](https://docs.mammoth.io/agents/safety).
4. Inspect the exit code and `error.code`. **Retry only exit code 7.**
5. After a write, read `data.verify` and `data.state` ([errors](https://docs.mammoth.io/build/errors)). Stop and report when `verify.needs_user` is set or `verified` is false.
6. Delete temporary resources when the run finishes, using the exact ids the run returned.

## Waiting on work

Three timeouts, because three different things can be slow:

- `--timeout`, per HTTP request.
- `--job-timeout`, waiting on an asynchronous job.
- `--pipeline-timeout`, waiting on a pipeline run.

Pass `--return-running` to exit 0 with `{status: running, …, resume}` when a job or pipeline wait runs out, instead of a timeout error. Continue it with `mammoth job wait JOB_ID`, which reports success, failure or still running and waits at most 15 minutes by default.

The bundled skill's own default: commands that start platform work wait up to 300 seconds for the job; on a `timeout` exit, use the `job get` recovery command the envelope printed rather than resubmitting the original mutation.

## Profiles

Name the credential profile explicitly in automation, so a run cannot pick up whatever was left configured on the machine:

```bash
mammoth project list --output json --no-input --profile production
```

Piped output already turns on `--output json --no-input`. `MAMMOTH_PROFILE`, `MAMMOTH_PROJECT`, `MAMMOTH_OUTPUT` and `MAMMOTH_NO_INPUT` also set session defaults, but never a credential. The CLI checks PyPI for a newer release once a day. It installs one by itself only in an interactive terminal, so a CI run or an agent never has its version changed under it; `MAMMOTH_AUTO_UPGRADE=1` forces the install on. `MAMMOTH_NO_UPDATE_CHECK=1` turns the check off, which suits a pinned CI image.

## Cleaning up

Use ids the run itself returned. List or preview the target first if the run may have been interrupted, then delete explicitly. **Never match on names broadly in a cleanup script**. The bundled skill calls this out directly: cleanup is exact-ID authorized, never "delete every resource this run might have created."

```bash
mammoth dataset list --project 180 --output json --no-input
mammoth dataset delete DATASET_ID --project 180 --yes --output json --no-input
```

---

**Next up:** [Blast radius and safety](https://docs.mammoth.io/agents/safety) for the mutation classes and confirmation policies in full · [Errors and exit codes](https://docs.mammoth.io/build/errors) for the envelope, the codes, and what is worth retrying.

---
Source: https://docs.mammoth.io/agents/ci.md · Updated: 2026-10-15