# Configuration

> Where clai keeps its configuration files, what each file holds, and the environment variables it reads.

Canonical URL: https://www.clai.chat/docs/reference/configuration/ · Version: 1.0 · Updated: 2026-10-22

Full site index: https://www.clai.chat/llms.txt

`clai` stores its configuration as readable JSON files in `<os.UserConfigDir()>/.clai`, which is `~/.config/.clai` on Linux. Run `clai confdir` to print the path, or set `CLAI_CONFIG_DIR` to use another directory.

The cache directory holds generated indexes and sits beside it at `<os.UserCacheDir()>/.clai`. Set `CLAI_CACHE_DIR` to move it.

## Configuration files

| Path                        | Purpose                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `textConfig.json`           | Default text model, system prompt, tools, summary model, and the token stop-loss policy. |
| `photoConfig.json`          | Default photo model, output directory, and filename prefix.                              |
| `videoConfig.json`          | Default video model, output directory, and filename prefix.                              |
| `audioConfig.json`          | Default audio transcription model and output format.                                     |
| `profiles/<name>.json`      | Named profile presets that override model, prompt, tools and MCP servers (`-p`, `-prp`). |
| `mcpServers/<name>.json`    | MCP server definitions: transport, command or URL, arguments and environment.            |
| `shellContexts/<name>.json` | Named shell context templates that `-asc` (`-add-shell-context`) evaluates.              |
| `skills.json`               | Agent Skills settings and the directories skills load from.                              |
| `conversations/`            | Saved conversation threads, the conversation index, and the global reply pointer.        |

`clai` creates a missing file from its defaults on first use. A new file overrides nothing, and a file that gains a field is upgraded in place with the new field's default; a `-r` (`-raw`) run never writes.

## Example textConfig.json

```json
{
  "model": "claude-sonnet-4-6",
  "system-prompt": "You are a helpful command-line assistant.",
  "raw": false,
  "save-reply-as-conv": true
}
```

## Environment variables

| Variable             | Purpose                                                  |
| -------------------- | -------------------------------------------------------- |
| `CLAI_CONFIG_DIR`    | Use another configuration directory than the default.    |
| `CLAI_CACHE_DIR`     | Use another cache directory than the default.            |
| `DEBUG`              | Print debug output when set to any non-empty value.      |
| `DEBUG_OUTPUT_FILE`  | Write debug output to this file instead of the terminal. |
| `ANTHROPIC_API_KEY`  | API key for Anthropic Claude models.                     |
| `OPENAI_API_KEY`     | API key for OpenAI models.                               |
| `GEMINI_API_KEY`     | API key for Google Gemini models.                        |
| `DEEPSEEK_API_KEY`   | API key for DeepSeek models.                             |
| `XAI_API_KEY`        | API key for xAI Grok models.                             |
| `OPENROUTER_API_KEY` | API key for OpenRouter models.                           |
| `MISTRAL_API_KEY`    | API key for Mistral models.                              |
| `BERGET_API_KEY`     | API key for Berget models.                               |
| `HF_API_KEY`         | API key for HuggingFace models.                          |
| `INCEPTION_API_KEY`  | API key for Inception models.                            |
| `NOVITA_API_KEY`     | API key for Novita models.                               |
| `TYPESAFE_API_KEY`   | API key for the Jev vendor.                              |
| `OLLAMA_API_KEY`     | Only for an Ollama-compatible endpoint that needs one.   |

Each vendor reads its key from the environment, so a key never belongs in a config file that you share. The [community hub](/hub/) refuses the common credential shapes, but you must still remove every secret before you publish a config.

## Related

- [CLI reference](/docs/reference/cli/) lists every flag.
- [Profiles and setup](/docs/guides/profiles/) covers the override cascade.
- [Agent Skills and shell context](/docs/guides/skills-and-shell-context/) covers the files those features read.