Skip to content
Try free
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 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:

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.

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

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

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