Global flags, environment and output

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 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:

{
  "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:

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