Configuration

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

{
  "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 refuses the common credential shapes, but you must still remove every secret before you publish a config.

Related

• CLI reference lists every flag.
• Profiles and setup covers the override cascade.
• Agent Skills and shell context covers the files those features read.