# Configuration

> Every configuration file under ~/.config/clai/ and the environment variables clai reads.

Canonical URL: https://www.clai.chat/docs/v0.1/reference/configuration/ · Version: 0.1 · Updated: 2026-10-21

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

`clai` stores all configuration as human-readable JSON and Markdown files inside `<os.UserConfigDir()>/clai` (or `$CLAI_CONFIG_DIR`).

## Configuration directory layout

| Path                        | Purpose                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `textConfig.json`           | Default text model, system prompt, tool truncation limits, and conversation settings.    |
| `photoConfig.json`          | Default photo generation model, output directory, and prompt prefix.                     |
| `videoConfig.json`          | Default video generation model, output directory, and prompt prefix.                     |
| `<vendor>_<model>.json`     | Per-model vendor parameters (temperature, token limits, endpoint overrides).             |
| `profiles/<name>.json`      | Named profile presets (`model`, `mprompt`, `tools`, `mcpServers`, `save_reply_as_conv`). |
| `mcpServers/<name>.json`    | MCP stdio server definitions (`command`, `args`, `env`).                                 |
| `skills/<name>/SKILL.md`    | User-global Agent Skills.                                                                |
| `shellContexts/<name>.json` | Named shell context templates for `-sc`.                                                 |
| `conversations/`            | Saved conversation threads and `globalScope.json`.                                       |
| `theme.json`                | Terminal color theme configuration.                                                      |

## 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,
  "tool-truncation-limit": 32768
}
```

## Flags and environment variables

| Function                                  | Flag             | Environment variable | Default                    |
| ----------------------------------------- | ---------------- | -------------------- | -------------------------- |
| Override the active chat model            | `--chat-model`   | `CLAI_CHAT_MODEL`    | `claude-sonnet-4-6`        |
| Override the active photo model           | `--photo-model`  | `CLAI_PHOTO_MODEL`   | `dall-e-3`                 |
| Override the active video model           | `--video-model`  | `CLAI_VIDEO_MODEL`   | `veo-3.0-generate-preview` |
| Load a named profile from `profiles/`     | `--profile`      | `CLAI_PROFILE`       | none                       |
| Load a profile JSON file by path          | `--profile-path` | `CLAI_PROFILE_PATH`  | none                       |
| Enable builtin tools or pass a glob       | `--tools`        | `CLAI_TOOLS`         | none                       |
| Fail immediately if an MCP server fails   | `--mcp-strict`   | `CLAI_MCP_STRICT`    | none                       |
| Print raw unformatted output without ANSI | `--raw`          | `NO_COLOR`           | none                       |
| Minimum log level                         | `--log-level`    | `LOG_LEVEL`          | `info`                     |
| Override the clai configuration directory | none             | `CLAI_CONFIG_DIR`    | `<user-config-dir>/clai`   |
| Override the clai cache directory         | none             | `CLAI_CACHE_DIR`     | `<user-cache-dir>/clai`    |
| clai.chat cloud sync token (Preview)      | none             | `CLAI_TOKEN`         | none                       |

## Vendor API key variables

| Variable             | Purpose                                                       |
| -------------------- | ------------------------------------------------------------- |
| `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.                             |
| `MISTRAL_API_KEY`    | API key for Mistral 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.                                |
| `DEBUG`              | Enable verbose debug logging when set to any non-empty value. |
| `DEBUG_CALL_ID`      | Print tool call IDs in terminal output when set.              |