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

# Global flags, environment and output

> The flags every mammoth command takes, environment variables, config paths, exit codes and the JSON envelope, verified against the CLI.

> Generated from mammoth-cli 2.4.2, released 2026-11-02: `mammoth schema list`, `mammoth capability list` and the CLI's own `--help`. Do not edit by hand; run `npm run docs:capabilities`.

These apply to every `mammoth` command, so the [family pages](https://mammoth.io/docs/build/cli/) do not repeat them. A flag goes after the command path: `mammoth project list --output json`.

## Global flags

Precedence for a setting is the flag, then its environment variable, then the profile's saved setting (`mammoth config set`: output, timeout, job_timeout, pipeline_timeout), then the default.

### Output and automation

| Flag | Value | Default | What it does |
|---|---|---|---|
| `--output`, `-o` | `auto\|table\|json\|yaml\|ndjson\|plain\|csv` | `auto` | Output format. 'auto' picks a table on a terminal, JSON when piped. |
| `--color` | `auto\|always\|never` | `auto` | Color policy. |
| `--no-input` | — | — | Never prompt; fail instead. |
| `--no-progress` | — | — | Never render progress. |
| `--debug` | — | — | Emit diagnostic detail to stderr. |

### Context and timeouts

| Flag | Value | Default | What it does |
|---|---|---|---|
| `--profile` | `str` | — | Credential profile name. |
| `--project` | `int` | — | Active project id override. |
| `--session` | `str` | — | Agent chat session id for 'agent action' and 'agent run' commands. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--timeout` | `float` | — | Per-request timeout seconds. |
| `--job-timeout` | `float` | — | Job wait timeout seconds. |
| `--return-running` | — | — | When a job or pipeline wait runs out, exit 0 with {status: running, job_id or dataview_id, resume} instead of a timeout error; resume with 'mammoth job wait JOB_ID' (reports success, failure or still running; waits at most 15 minutes by default). Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--pipeline-timeout` | `float` | — | Pipeline wait timeout seconds. |

### Safety

| Flag | Value | Default | What it does |
|---|---|---|---|
| `--yes`, `-y` | — | — | Confirm a mutation without prompting. Not taken by `auth login`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`. |
| `--confirm` | `str` | — | Exact target name required for high-impact actions. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--dry-run` | — | — | Resolve and validate, then report the request instead of sending it. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--allow-empty` | — | — | Add a keep filter that matches no row; without it the dry run fails. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--overwrite` | — | — | Replace a local file the command writes to when it already exists. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |
| `--standing` | — | — | Stage a step that changes no row today, as a rule for future data. Not taken by `auth login`, `auth logout`, `auth status`, `config get`, `config list`, `config path`, `config set`, `context project clear`, `context project status`, `context project use`, `context show`, `upgrade`. |

### Request input

| Flag | Value | Default | What it does |
|---|---|---|---|
| `--input` | `str` | — | Strict JSON/YAML request document, or '-' for stdin. |
| `--input-format` | `str` | — | Required for stdin: json or yaml. |

## Confirmation

Each command has a confirmation policy, shown on its family page and in `mammoth schema get COMMAND_ID`. The CLI enforces it before sending anything (`runtime/confirm.py`):

| Policy | What the command needs |
|---|---|
| `none` | Nothing. |
| `prompt_or_yes` | `--yes`. Without it, the CLI asks only when stdin is a terminal, `--no-input` is not set and `--output` is not `json` or `ndjson`; otherwise it fails with `confirmation_required`. |
| `yes_always` | `--yes`, always. It never prompts, even at a terminal. |
| `confirm_target` | `--yes --confirm TARGET`, always, where TARGET is exactly the id or name the command acts on. A missing `--yes` fails with `confirmation_required`; a different `--confirm` fails with `confirmation_target_mismatch`. |

`--dry-run` skips confirmation: it validates and reports the request without sending it. A `--confirm` that does not match the command's positional target is refused, never ignored. The `confirmation_required` error's hint names the exact flags to re-run with.

## Environment variables

| Variable | Effect |
|---|---|
| `MAMMOTH_API_TOKEN` | An `mm_...` API token. Used instead of the saved profile's credentials, unless a profile is named with `--profile` or `MAMMOTH_PROFILE`. The CLI prints `Using MAMMOTH_API_TOKEN for <url>` to stderr when it does. |
| `MAMMOTH_SERVER_PREFIX` | Server prefix (one DNS label) for `MAMMOTH_API_TOKEN`. Default `app`. |
| `MAMMOTH_PROFILE` | Profile to use when `--profile` is not given. Counts as naming a profile, so it outranks `MAMMOTH_API_TOKEN`. |
| `MAMMOTH_PROJECT` | Project id to use when `--project` is not given. Must be a positive integer. |
| `MAMMOTH_OUTPUT` | Output mode when `--output` is left at `auto`. |
| `MAMMOTH_NO_INPUT` | `1`, `true`, `yes` or `on`: same as `--no-input`. |
| `MAMMOTH_JSON_PRETTY` | `1`/`true`/`yes`/`on` forces indented JSON, anything else compact. Unset: indented only on a terminal. |
| `MAMMOTH_LOG_DIR` | Where the local run log is written (kept 7 days). Read it with `mammoth log`. |
| `MAMMOTH_NO_UPDATE_CHECK` | Truthy: no daily check for a newer CLI on PyPI, and no self-upgrade. |
| `MAMMOTH_NO_AUTO_UPDATE` | Truthy: never upgrade the CLI by itself. |
| `MAMMOTH_AUTO_UPGRADE` | `1` lets the CLI upgrade itself even in CI or without a terminal; `0` turns it off. Unset: only in an interactive terminal session with no CI variable set. |
| `MAMMOTH_AGENT` | Names the coding agent driving the CLI, sent with each request. Otherwise detected from `CLAUDECODE`, `CURSOR_AGENT`, `GEMINI_CLI` or `CODEX_SANDBOX`. |

Truthy means `1`, `true`, `yes` or `on`. A run in CI (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI` and similar set) counts as non-interactive for self-upgrade.

## Files

| What | Where |
|---|---|
| Profiles and saved settings (no secrets) | `profiles.toml` in `platformdirs.user_config_dir("mammoth-cli", "Mammoth")`: `~/Library/Application Support/mammoth-cli/` on macOS, `~/.config/mammoth-cli/` on Linux |
| Credentials | The OS keyring (service `mammoth-cli`, one entry per profile); where there is no keyring, `credentials.toml` beside `profiles.toml`, mode 0600 |
| Run log | `platformdirs.user_state_dir("mammoth-cli", "Mammoth")/logs` (or `MAMMOTH_LOG_DIR`), kept 7 days; `mammoth log` reads it |

## Exit codes

| Exit | Name | Meaning |
|---|---|---|
| 0 | `EXIT_OK` | Success. |
| 1 | `EXIT_API` | The API returned an error. |
| 2 | `EXIT_USAGE` | Usage error: bad arguments or input, or a missing or mismatched confirmation. |
| 3 | `EXIT_PARTIAL` | Partial success: some of the work, or its read-back, failed. |
| 4 | `EXIT_AUTH` | Not signed in, or not allowed. |
| 5 | `EXIT_NOT_FOUND` | The resource does not exist. |
| 6 | `EXIT_CONFLICT` | Conflict with the resource's current state. |
| 7 | `EXIT_RETRYABLE` | Temporary failure; safe to retry. |
| 130 | `EXIT_INTERRUPT` | Interrupted (Ctrl-C). |

## Output and envelopes

`--output auto` (the default) prints a table on a terminal and JSON when stdout is piped. In `json` and `ndjson` mode stdout carries exactly one envelope, success or error, and diagnostics go to stderr; in `table`, `plain` and `csv` mode an error is a short `error [code]: message` line on stderr.

Success:

```json
{
  "schema_version": 1,
  "data": { "...": "the command's result" },
  "meta": { "command": "project list", "profile": "default", "workspace_id": 1, "project_id": 2,
            "pagination": {}, "dataset": {}, "view": {}, "opens": [], "update_available": {},
            "next_commands": [], "exit": 0, "run_id": "..." }
}
```

`meta` keys that are null are left out. `meta.next_commands` holds ready-to-run follow-ups and `meta.opens` the objects a write made or changed.

Error:

```json
{
  "schema_version": 1,
  "error": { "code": "confirmation_required", "summary": "...", "message": "...", "hint": "...",
             "details": {}, "request_id": null, "retryable": false, "authorization_required": false,
             "recovery_commands": [], "exit": 2, "log_ref": "..." }
}
```

Branch on `error.code` (stable) and the exit status, not on `message`. `recovery_commands` are runnable as written. `--output ndjson` frames the same data as `start`, `item` and `end` events (or one `error` event).

Sources: `mammoth_cli/context/credentials.py`, `mammoth_cli/context/profiles.py`, `mammoth_cli/context/resolver.py`, `mammoth_cli/errors/envelope.py`, `mammoth_cli/output/emit.py`, `mammoth_cli/output/envelope.py`, `mammoth_cli/output/render.py`, `mammoth_cli/runtime/invocation.py`, `mammoth_cli/runtime/runlog.py`, `mammoth_cli/runtime/trace.py`, `mammoth_cli/runtime/updates.py`.

---
Source: https://mammoth.io/docs/build/cli/global-flags.md · Updated: 2026-11-03