Common flags

Every verb supports the same cross-cutting flags. Verb-specific flags live on each verb's page.

--retries and --timeout are scoped:

• Available on: AI generation (run, image, speak, transcribe), sync data verbs (search, scrape, answer, map, enrich, lookup, verify), and the initial submission of async verbs (research, crawl, findall).
• Not available on: get (already a polling primitive — control retry via your own loop) or api <provider> (raw passthrough — wrap your own retry).
• On async verbs, --retries retries the initial submission only. The polling loop has its own backoff and is not affected.
• When a retry fires, marmot prints a one-line note to stderr: [retry 1/3] tavily search: HTTP 429 — backing off 800ms. Useful for spotting silent-double-billing on paid providers.

Output

Each verb has a default output format and a flag to override it.

Override flags:

List/get commands (preset list/get, session list/get, providers list, tasks list/get)

These commands now ship a TTY-aware default: human-readable table or key/value layout on an interactive terminal, the JSON envelope when piped or redirected. Pass --json to force JSON, or --markdown for a markdown pipe-table (handy when embedding output in docs / Slack / GitHub comments). --json and --markdown are mutually exclusive.

marmot preset list                 # human table on TTY
marmot preset list | jq            # JSON (piped → fallback)
marmot preset list --markdown      # markdown table, regardless of TTY

Async verbs

research, crawl, and findall are async. They take two extra flags.

See Async tasks.

Cache flags (web and data sync verbs)

search, scrape, answer, map, enrich, lookup, and verify all share two flags for the response cache. Caching is opt-in per provider; these flags only matter when providers.<slug>.cache.enabled is true.

See Caching for the full model and the marmot cache subcommands.

Stdout decision matrix

Every verb that accepts -o <file> resolves what to send to stdout using these rules:

--quiet only governs stdout. Stderr (spinners, cache hints, warnings, errors) is unaffected.

Examples:

# Write to file, stay silent — common case.
marmot run "summarize this" -o out.md

# Write to file AND consume in a pipe.
marmot run "summarize this" -o out.md | grep -i critical

# Force silence even when piped (write file only, pipe gets nothing).
marmot search "openrouter pricing" -o out.json --quiet

# Want to watch the stream AND save it? Drop -o and use shell tee.
marmot run --stream "long answer" | tee out.md

The matrix applies to AI verbs (run, transcribe, image, speak, video) and web/data verbs (search, scrape, answer, map, crawl, research, findall, enrich, lookup, verify).

stdout vs stderr

Marmot keeps results on stdout and status on stderr, so pipelines stay clean.

Spinners and cache messages disable themselves automatically when stderr is not a TTY (CI runners, redirected output) or when CI=true or NO_COLOR=1 is set.

Resolution order

For --provider, --model, and any other configurable default:

1. Explicit flag on the command line
2. ~/.marmot/config.json, set via marmot setup or marmot config set
3. First-run auto-config: if no default is set for an AI verb (text, image, speech, transcription), marmot detects available API keys in your environment and picks the first ready provider in this order: ollama (local) → openrouter → vercel → cloudflare → openai → anthropic. The choice is persisted to ~/.marmot/config.json and a one-line stderr note announces it. You can override later with marmot setup or marmot config set.
4. Error, with a hint listing every supported provider's env var and a link to where to get a key.