Skip to content
Mammoth for coding agents: open the docs menu

Mammoth CLI in agents and CI

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.

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 takes credentials without one in three ways.

In CI, the environment variable. Put the API token in your CI secret store and expose it as MAMMOTH_API_TOKEN. The CLI reads it on every command, with no sign-in step. MAMMOTH_SERVER_PREFIX names a region other than the default app.

# MAMMOTH_API_TOKEN comes from the CI secret store
mammoth doctor --output json --no-input
mammoth project list --output json --no-input

While the variable is set it outranks any saved profile, and the CLI prints one stderr line saying so. Naming a profile, with --profile NAME or MAMMOTH_PROFILE, outranks the variable.

A credentials file, once. The operator provisions an owner-only (0600) file out of band, created with those permissions from the start, not chmod-ed afterwards, and the run consumes it once to save a profile:

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. --storage file is explicit on POSIX: --storage auto can require an OS keyring that a CI runner does not have.

A coding agent with a person nearby: the device code. The agent runs mammoth auth login --device, shows the person the link and code it prints, and waits while they approve in their browser. This is what the bundled skill tells an agent to do.

Create the API token in Settings → API Keys → Generate key. A token limited to one project gets HTTP 403 in every other project, so pass that project with --project ID.

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.

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.
  4. Inspect the exit code and error.code. Retry only exit code 7.
  5. After a write, read data.verify and data.state (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

With MAMMOTH_API_TOKEN set, the run uses that token. Without it, name the credential profile explicitly in automation, so a run cannot pick up whatever was left configured on the machine:

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 set session defaults. MAMMOTH_API_TOKEN and MAMMOTH_SERVER_PREFIX are the only variables that carry a credential, and the token outranks the saved profile unless one is named with --profile or MAMMOTH_PROFILE. 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."

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 for the mutation classes and confirmation policies in full · Errors and exit codes for the envelope, the codes, and what is worth retrying.

Report an issue · support@mammoth.io