Configuration

Marmot keeps your default provider and model for each verb in a single config file at ~/.marmot/config.json. marmot setup and marmot config set write to it for you. This page lists every key the file accepts.

Top level

The shape on disk:

{
  "version": 1,
  "defaults":  { … },
  "providers": { … },
  "presets":   { … }
}

marmot config show --json returns the same envelope plus three runtime-derived fields, so an agent or script can read its full bootstrap signal in a single call:

{
  "marmotVersion": "0.4.0",
  "version": 1,
  "defaults": { … },
  "providers": { … },
  "presets": { … },
  "readyProviders": ["ollama", "openrouter", "tavily"],
  "cache": { "totals": { … }, "providers": [ … ] }
}

Defaults

Every key under defaults is optional. Resolution differs by verb type:

• AI verbs (text, image, speech, transcription, video): with no default and no --provider flag, marmot runs first-run auto-config — it detects available API keys in your env, picks the first ready provider in pecking order (ollama → openrouter → vercel → cloudflare → openai → anthropic; image/speech/transcription skip ollama and anthropic; video only routes through openrouter and vercel), persists the choice to this file, and continues the call. A one-line stderr note announces it.
• Web/data verbs (search, scrape, enrich, lookup, verify, etc.): no auto-config. With no default and no --provider, the call errors and points you at marmot setup.

{
  "defaults": {
    "text":          { "provider": "openrouter", "model": "openai/gpt-oss-120b" },
    "image":         { "provider": "openrouter", "model": "google/gemini-2.5-flash-image" },
    "speech":        { "provider": "openrouter", "model": "openai/gpt-4o-mini-tts-2025-12-15", "voice": "alloy" },
    "transcription": { "provider": "openrouter", "model": "openai/gpt-4o-transcribe" },
    "video":         { "provider": "openrouter", "model": "google/veo-3.1-lite" },

    "search":   { "provider": "tavily" },
    "scrape":   { "provider": "firecrawl" },
    "answer":   { "provider": "tavily" },
    "map":      { "provider": "tavily" },
    "crawl":    { "provider": "firecrawl" },
    "research": { "provider": "parallel" },
    "findall":  { "provider": "parallel" }
  }
}

AI verbs

Web data verbs

People and org verbs

Data verbs only store provider. There is no per-verb model concept on these. The enrich, lookup, and verify defaults gate which provider serves the verb. The capability matrix per --type (person, org, email) lives on each verb's page.

Providers

Per-provider settings, keyed by provider slug. All fields optional. Applies to AI, web, and data providers uniformly.

{
  "providers": {
    "tavily": {
      "enabled": true,
      "cache": { "enabled": true, "ttlDays": 30 }
    },
    "apollo": {
      "apiKeyEnvVar": "MY_APOLLO_KEY"
    },
    "tomba": {
      "apiKeyEnvVar": "WORK_TOMBA_KEY",
      "apiSecretEnvVar": "WORK_TOMBA_SECRET"
    }
  }
}

Auth resolution order, per credential:

1. --api-key flag on the command line
2. providers.<slug>.apiKeyEnvVar env var if configured
3. Built-in env var (APOLLO_API_KEY, TAVILY_API_KEY, etc.)

See Caching for the full cache model.

Resolution order

1. Command-line flag for the call
2. ~/.marmot/config.json
3. Error, with a hint to run marmot setup

Setting keys from the CLI

Three key shapes are accepted:

# AI verb defaults (under defaults.<verb>.<field>)
marmot config set text.provider anthropic
marmot config set image.model google/gemini-2.5-flash-image
marmot config set speech.voice alloy

# Web/data verb defaults (under defaults.<verb>.provider)
marmot config set search.provider tavily
marmot config set enrich.provider pdl

# Per-provider settings (under providers.<slug>.<field>)
marmot config set providers.tavily.cache.enabled true
marmot config set providers.tavily.cache.ttlDays 14
marmot config set providers.apollo.apiKeyEnvVar MY_APOLLO_KEY
marmot config set providers.openrouter.enabled false

Boolean values must be true or false. ttlDays must be a positive integer.

marmot config unset providers.tavily.cache.ttlDays  # remove a single key
marmot config show                                  # human-readable
marmot config show --json                           # raw envelope
marmot config path                                  # print the config file path

Reading a single key — marmot config get

marmot config get <key> prints one value to stdout. Primitives render bare so shells can capture them with $(); objects and sub-buckets pretty-print as JSON. Missing keys exit non-zero with a stderr message so scripts can branch with marmot config get x || ....

$ marmot config get text.provider
openrouter

$ marmot config get logging.recordSensitive
false

$ marmot config get providers.openai.cache
{
  "enabled": true,
  "ttlDays": 30
}

Accepts the same dotted-path keys as config set, plus any of their bucket prefixes (providers, providers.openai, providers.openai.cache, text, etc.). A typo gets the same "valid shapes" hint as config set.

The human-readable marmot config show output (no --json) prints:

• Installed marmot version and the path to the config file
• AI defaults (text, image, video, transcription, speech)
• Web defaults (search, scrape, research, answer, crawl, map, findall)
• Data defaults (enrich, lookup, verify)
• Ready providers grouped by category (AI / Web / Data) — same source as the JSON readyProviders field
• Response cache totals (and per-provider breakdown — see Caching)