> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Reference (.env)
> A complete guide to all environment variables you can configure in your .env file to customize ChatCLI.
**ChatCLI** is extensively configurable through environment variables. Create a `.env` file in the project root or in your `HOME` directory.
### Priority Order
E.g.: `--provider`, `--model` (highest priority)
`export LLM_PROVIDER=OPENAI`
`LLM_PROVIDER=OPENAI`
ChatCLI internal defaults (lowest priority)
***
## General Configuration
| Variable | Description | Default |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------- |
| `CHATCLI_ENV` | Logging mode: `dev` (colored console + file), `prod` (file-only JSON). Backward-compatible with legacy `ENV`. | `prod` |
| `LLM_PROVIDER` | Sets the default AI provider to use. Valid values: `OPENAI`, `OPENAI_ASSISTANT`, `CLAUDEAI`, `BEDROCK`, `GOOGLEAI`, `XAI`, `ZAI`, `MINIMAX`, `MOONSHOT`, `OPENROUTER`, `STACKSPOT`, `OLLAMA`, `COPILOT`, `GITHUB_MODELS`. | `"OPENAI"` |
| `CHATCLI_LANG` | Sets the interface language. Values: `pt-BR`, `en-US`. If not set, it will attempt to detect the system language. | `en-US` |
| `LOG_LEVEL` | Log level. Options: `debug`, `info`, `warn`, `error`. | `"info"` |
| `LOG_FILE` | Path to the log file. Default: `$HOME/.chatcli/app.log` | `"$HOME/.chatcli/app.log"` |
| `LOG_MAX_SIZE` | Maximum log file size before rotation. Accepts `100MB`, `50KB`, etc. | `"100MB"` |
| `HISTORY_MAX_SIZE` | Maximum history file (`.chatcli_history`) size before rotation. | `"100MB"` |
| `HISTORY_FILE` | Custom path for the history file (supports `~`; by default it creates the history where chatcli was executed). | `".chatcli_history"` |
| `CHATCLI_DOTENV` | Custom path for your `.env` file. | `".env"` |
| `CHATCLI_IGNORE` | Path to ignore file (e.g., `.chatignore`). When set, it takes priority over project/global ignore. | `""` |
| `CHATCLI_CODER_UI` | Timeline style for `/coder` and `/agent` modes (cross-mode since v1.119): `full` · `compact` · `minimal`. See [UI Styles](#ui-styles). | `"full"` |
| `CHATCLI_CODER_BANNER` | Display the `/coder` quick cheat sheet when entering the session (`true`/`false`). | `"true"` |
| `CHATCLI_THEME` | Color theme for the whole interface (chat, cards, markdown, spinners). **11 themes:** `dark`, `light` + 9 community palettes. Switch at runtime via `/config ui theme`. See the [Color Theme](#color-theme) section. | `"dark"` |
## Color Theme
`CHATCLI_THEME` selects the **color palette** that re-skins the entire interface — chat, `/coder` and `/agent` cards, borders, markdown, code blocks, and spinners. Unlike `CHATCLI_CODER_UI`, the theme is process-global state, so a switch applies on the **next render, with no restart**.
There are **11 themes**: `dark` and `light` (ChatCLI's calibrated variants) + nine community palettes — `dracula`, `nord`, `tokyo-night`, `solarized-dark`, `solarized-light`, `gruvbox`, `catppuccin-mocha`, `monokai`, `one-dark`. Real-color previews of each are in the [Theme System](/features/ui-theme).
```bash theme={"system"}
/config ui # show the active theme + detected color profile
/config ui theme dark # switch to the dark theme
/config ui theme dracula # switch by name (any of the 11)
/config theme tokyo-night # shorthand equivalent
```
Autocomplete: `/config ui theme ` (or `/config theme `) offers all 11 themes.
The switch applies only to the current process. To persist it, add `CHATCLI_THEME=light` to your `.env` — the mutator prints this hint after every switch and **never rewrites your `.env`** on its own. In pipes, CI, or colorless terminals (`NO_COLOR`, `dumb`), output degrades to clean plain text. Full details in the [Theme System](/features/ui-theme).
## UI Styles
`CHATCLI_CODER_UI` controls **how `/coder` and `/agent` modes** render tool calls, reasoning and results in the timeline. Before v1.119 it only affected `/coder`; from that version onward **it applies to `/agent` too** — anyone with `CHATCLI_CODER_UI=compact` already set will see `/agent` go compact as well.
| Value | Appearance | When to use |
| ---------------- | -------------------------------------------------------------------------------------- | --------------------------------------------- |
| `full` (default) | Full bordered cards `╭── ICON TITLE ─────╮ … ╰─────╯`. Each action is a visible block. | `/agent` supervised — plan-and-approve. |
| `compact` | Inline lines `↻ Read(main.go)` / `✓ Read(main.go) 0.3s`. Short messages, no cards. | `/coder` with long sessions (20+ tool calls). |
| `minimal` | Smaller cards with truncated content. Middle ground. | Mixed sessions in narrow terminals. |
### Switch the UI at runtime
Since v1.119 you can swap the style **without restarting** ChatCLI, right from the prompt:
```bash theme={"system"}
/config agent ui # show current style + options
/config agent ui compact # switch to compact (takes effect on the next /coder or /agent)
/config agent ui full # back to the default
/config agent ui minimal # middle ground
```
Full autocomplete — type `/config agent ` and then `/config agent ui ` to see `full | compact | minimal`.
The change applies only to the current process. To persist across sessions, add `CHATCLI_CODER_UI=compact` (or any other value) to your `.env` — the mutator prints that hint right after every switch.
### Parallel visual changes (v1.119)
* **Card footers** now end at the content width (`╰────╯`) instead of stretching to the terminal edge.
* **Errors in true red** (`✗`, `❌ EXECUTION FAILED`) instead of purple. If your terminal maps ANSI 31 to a non-red color via theme, adjust the palette.
* **Unified banner** for `/coder` and `/agent`: same entry card with Objective/Task, Workspace and Policy.
* **`/agent` menu** reorganized into 3 columns (Execution · Edit & Context · View) — was a 12-line vertical list before.
* **Prompt prefix** groups all badges (`[🌐 ⏵ ▶2⏳1 🅿1]`) instead of listing `[remote] [watch] [jobs:…] [🅿️ resume:…]` separately.
* **Chat turn header**: new envelope `╭─ model ─── 1.4s · 312↑ 1800↓ ─╮ … ╰─╯` in chat mode, with latency and estimated tokens.
## Context and Output Compression
Runtime control of [Context Compression (CCR)](/features/context-compression) and output-token reduction. Changes take effect immediately; set the variables in `.env` for a permanent default.
```bash theme={"system"}
# Input compression (tool output, logs, diffs, JSON, prose)
/config compression # panorama: mode, threshold, CCR store, savings
/config compression lossy # full reduction, reversible via @recall (default)
/config compression lossless # lossless reductions only (no line dropping)
/config compression off # disable
/config compression stats # per-strategy savings summary
# Output-token reduction
/config output # panorama: verbosity + effort routing
/config output concise # trim ceremony, keep substance (default)
/config output minimal # fewest correct tokens
/config output full # no steering
/config output effort on|off # complexity-based effort routing (opt-in)
```
The `@compress`/`@recall` tools expose on-demand compression to the model. See the [Context Compression](/features/context-compression) page for details, environment variables and never-degrade guarantees.
## OAuth Authentication
In addition to traditional API keys, ChatCLI supports **OAuth authentication** for OpenAI, Anthropic, and GitHub Copilot. With OAuth, you can use your existing plan (ChatGPT Plus, Codex, Claude Pro, GitHub Copilot) without generating API keys.
| Variable | Description | Default |
| :-------------------------- | :---------------------------------------------------- | :------------ |
| `CHATCLI_AUTH_DIR` | Directory where OAuth credentials are stored. | `~/.chatcli/` |
| `CHATCLI_OPENAI_CLIENT_ID` | Allows overriding the OpenAI OAuth client ID. | (internal) |
| `CHATCLI_COPILOT_CLIENT_ID` | Allows overriding the GitHub Copilot OAuth client ID. | (internal) |
Credentials are stored with **AES-256-GCM encryption** in `~/.chatcli/auth-profiles.json`. The encryption key is automatically generated and saved in `~/.chatcli/.auth-key` (permission 0600).
> Use `/auth login openai-codex`, `/auth login anthropic`, or `/auth login github-copilot` in interactive mode to start the OAuth flow. See the [full OAuth documentation](/features/oauth-authentication) for more details.
***
## Provider Configuration
### OpenAI
| Variable | Description | Required? |
| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- |
| `OPENAI_API_KEY` | Your secret OpenAI API key. Alternative: use `/auth login openai-codex` for OAuth. | **Yes**\* |
| `OPENAI_MODEL` | The model to use. E.g.: `gpt-5.6-sol`, `gpt-5.6-luna`, `gpt-5.4`, `gpt-4o`. | No |
| `OPENAI_ASSISTANT_MODEL` | The model to use specifically for the Assistants API. | No |
| `OPENAI_USE_RESPONSES` | Set to `true` to force the `v1/responses` API for every model. Setting `false` does not force `v1/chat/completions`: OAuth sessions and models whose catalog entry prefers the Responses API (e.g. `gpt-5.4`) still use it. | No |
| `OPENAI_API_URL` | Custom Chat Completions endpoint. Must be the full URL ending in `/chat/completions`; the `/models` listing URL is derived from it. With a custom host the model listing is not filtered by family, and `OPENAI_API_KEY` is still sent as the Bearer token (set it to the gateway's key). | No |
| `OPENAI_RESPONSES_API_URL` | Custom Responses API endpoint. Set both URLs when redirecting the provider to an OpenAI-compatible endpoint. | No |
| `OPENAI_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
### Anthropic (Claude)
| Variable | Description | Required? |
| :---------------------- | :--------------------------------------------------------------------------------- | :-------- |
| `ANTHROPIC_API_KEY` | Your secret Anthropic API key. Alternative: use `/auth login anthropic` for OAuth. | **Yes**\* |
| `ANTHROPIC_MODEL` | The model to use. E.g.: `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-4-6`. | No |
| `ANTHROPIC_API_VERSION` | The Anthropic API version to use in headers. | No |
| `ANTHROPIC_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
| `ANTHROPIC_SPEED` | Set to `fast` to opt in to Opus 4.8 fast mode (research preview, premium pricing). | No |
### Google (Gemini)
| Variable | Description | Required? |
| :-------------------- | :--------------------------------------------------------------- | :-------- |
| `GOOGLEAI_API_KEY` | Your Google AI Studio API key. | **Yes** |
| `GOOGLEAI_MODEL` | The model to use. E.g.: `gemini-2.5-pro`, `gemini-2.5-flash`. | No |
| `GOOGLEAI_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
### xAI (Grok)
| Variable | Description | Required? |
| :--------------- | :--------------------------------------------------------------- | :-------- |
| `XAI_API_KEY` | Your secret xAI API key. | **Yes** |
| `XAI_MODEL` | The model to use. E.g.: `grok-4-1`, `grok-4-fast`, `grok-3`. | No |
| `XAI_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
### Ollama (Local)
| Variable | Description | Required? |
| :----------------------- | :------------------------------------------------------------------------------------------- | :-------- |
| `OLLAMA_ENABLED` | Set to `true` to enable the Ollama provider. | **Yes** |
| `OLLAMA_BASE_URL` | Base URL of your local Ollama server. | No |
| `OLLAMA_MODEL` | The name of the local model to use (e.g., `llama3`, `codellama`). | No |
| `OLLAMA_FILTER_THINKING` | Filters intermediate reasoning in responses (e.g., for `Qwen3`, `llama3` default `true`...). | No |
| `OLLAMA_MAX_TOKENS` | Sets the maximum tokens for the Ollama provider. | No |
### StackSpot
| Variable | Description | Required? |
| :------------------- | :------------------------------------------------- | :-------- |
| `CLIENT_ID` | StackSpot client ID credential. | **Yes** |
| `CLIENT_KEY` | StackSpot client key credential. | **Yes** |
| `STACKSPOT_REALM` | Your organization's `realm` (tenant) on StackSpot. | **Yes** |
| `STACKSPOT_AGENT_ID` | The ID of the specific agent to use. | **Yes** |
### ZAI (Zhipu AI)
| Variable | Description | Required? |
| :--------------- | :----------------------------------------------------------------------------------------------- | :-------- |
| `ZAI_API_KEY` | Your ZAI (Zhipu AI) API key. Accepts plain Bearer token or `id.secret` format for automatic JWT. | **Yes** |
| `ZAI_MODEL` | The model to use. E.g.: `glm-5.2`, `glm-5`, `glm-4.7`, `codegeex-4`. | No |
| `ZAI_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
**Automatic JWT rotation:** Keys in `id.secret` format automatically enable JWT token generation (HMAC-SHA256) with custom header `{"alg": "HS256", "sign_type": "SIGN"}`. Tokens are cached for 30 minutes and regenerated with a 5-minute safety margin. Keys without "." continue to work as traditional Bearer tokens. Fully automatic, no additional configuration needed.
### MiniMax
| Variable | Description | Required? |
| :------------------- | :---------------------------------------------------------------------------- | :-------- |
| `MINIMAX_API_KEY` | Your MiniMax API key. | **Yes** |
| `MINIMAX_MODEL` | The model to use. E.g.: `MiniMax-M2.7`, `MiniMax-M2.5` (case-sensitive). | No |
| `MINIMAX_MAX_TOKENS` | Sets the maximum tokens to use in the session (depends on model) | No |
| `MINIMAX_API_COMPAT` | Compatibility mode: `anthropic` to use MiniMax's Anthropic Messages endpoint. | No |
**Anthropic-compatible endpoint:** Set `MINIMAX_API_COMPAT=anthropic` to use `https://api.minimax.io/anthropic/v1/messages` with Anthropic Messages format (system as top-level field, content blocks). The `anthropic-version: 2023-06-01` header is added automatically. Same Bearer token auth is used. Native tool calling is disabled in this mode (falls back to XML). Also available via Helm (`secrets.minimaxApiCompat: "anthropic"`) or Docker (`MINIMAX_API_COMPAT=anthropic`).
**Alternative approach (recommended by MiniMax):** Per the [official MiniMax documentation](https://platform.minimax.io/docs/guides/quickstart-preparation), you can use MiniMax models directly through the **CLAUDEAI provider** without needing `MINIMAX_API_COMPAT`. Simply configure the Anthropic base URL to point to MiniMax:
```env theme={"system"}
LLM_PROVIDER=CLAUDEAI
ANTHROPIC_API_KEY=your-minimax-key
ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
ANTHROPIC_MODEL=MiniMax-M2.7
```
This works because MiniMax's `api.minimax.io/anthropic` endpoint is 100% compatible with the Anthropic API. Use this approach to leverage Anthropic's native tool calling with MiniMax models.
### Moonshot (Kimi)
| Variable | Description | Required? |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :-------- |
| `MOONSHOT_API_KEY` | Bearer token API key from Moonshot AI. | **Yes** |
| `MOONSHOT_MODEL` | Model to use (`kimi-k2.6`, `kimi-k2.5`, `kimi-latest`, `kimi-thinking-preview`, `moonshot-v1-128k`, `moonshot-v1-32k`, `moonshot-v1-8k`). | No |
| `MOONSHOT_MAX_TOKENS` | Sets the maximum response tokens. | No |
| `MOONSHOT_THINKING` | Reasoning mode: `enabled`, `disabled`, `auto`. Models without the `thinking` capability ignore the flag. | No |
| `MOONSHOT_API_URL` | Custom endpoint. Default: `https://api.moonshot.ai/v1/chat/completions`. With a custom host, the model listing is not filtered by family. | No |
**Thinking vs Instant mode:** Default `auto` lets the model choose; `enabled` forces explicit reasoning (higher latency, more tokens); `disabled` forces direct response. Useful for switching between tasks that benefit from chain-of-thought and fast responses (extraction, classification). The flag is injected via `extra_body.thinking.type` in the OpenAI-compatible payload.
### OpenRouter
| Variable | Description | Required? |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- | :-------- |
| `OPENROUTER_API_KEY` | Your OpenRouter API key from [openrouter.ai](https://openrouter.ai). | **Yes** |
| `OPENROUTER_API_URL` | Custom API endpoint URL. | No |
| `OPENROUTER_MAX_TOKENS` | Sets the maximum tokens for the response. | No |
| `OPENROUTER_FALLBACK_MODELS` | Comma-separated fallback models for server-side routing (e.g., `anthropic/claude-sonnet-4,google/gemini-2.5-flash`). | No |
| `OPENROUTER_PROVIDER_ORDER` | Comma-separated preferred provider ordering (e.g., `Anthropic,Google`). | No |
| `OPENROUTER_TRANSFORMS` | Message transforms (e.g., `middle-out` for context overflow). | No |
| `OPENROUTER_HTTP_REFERER` | Attribution HTTP Referer header. | No |
| `OPENROUTER_APP_TITLE` | Attribution app title. | No |
| `OPENROUTER_TOOLS` | JSON array of tool definitions to inject. | No |
OpenRouter is a **multi-provider API gateway** that provides access to 200+ models from all major providers through a single API key. Models use the `provider/model-name` format (e.g., `openai/gpt-4o`, `anthropic/claude-sonnet-4`). The default model is `openai/gpt-4o`.
```env theme={"system"}
LLM_PROVIDER=OPENROUTER
OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxx"
# (Optional) Model — default: openai/gpt-4o
# MODEL="anthropic/claude-sonnet-4"
# (Optional) Server-side fallback routing
# OPENROUTER_FALLBACK_MODELS="anthropic/claude-sonnet-4,google/gemini-2.5-flash"
```
### GitHub Copilot
| Variable | Description | Required? |
| :--------------------- | :----------------------------------------------------------------------------------------- | :-------- |
| `GITHUB_COPILOT_TOKEN` | GitHub Copilot OAuth token. Alternative: use `/auth login github-copilot` for Device Flow. | **Yes**\* |
| `COPILOT_MODEL` | The model to use. E.g.: `gpt-4o`, `claude-sonnet-4`, `gemini-2.0-flash`. | No |
| `COPILOT_MAX_TOKENS` | Sets the maximum tokens for the response. | No |
| `COPILOT_API_BASE_URL` | Copilot API base URL (for enterprise environments). | No |
### AWS Bedrock
| Variable | Description | Required? |
| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------- |
| `AWS_PROFILE` | AWS profile in `~/.aws/credentials` or `~/.aws/config` (supports SSO, assume-role, credential\_process). Can be set in `.env`. | **Yes**\* |
| `AWS_ACCESS_KEY_ID` | Static IAM access key. Alternative to `AWS_PROFILE`. | **Yes**\* |
| `AWS_SECRET_ACCESS_KEY` | IAM secret key (required with `AWS_ACCESS_KEY_ID`). | **Yes**\* |
| `AWS_SESSION_TOKEN` | Temporary session token (STS). | No |
| `BEDROCK_REGION` | AWS region for Bedrock (takes priority over `AWS_REGION`). | No |
| `AWS_REGION` | AWS region (fallback if `BEDROCK_REGION` not set). | No |
| `BEDROCK_PROVIDER` | Manual schema override: `anthropic` or `openai`. | No |
| `BEDROCK_ANTHROPIC_ENDPOINT` | Forces the Claude wire: `mantle` (Messages endpoint) or `invoke` (legacy InvokeModel). | No |
| `BEDROCK_MANTLE_BASE_URL` | Messages endpoint override (`bedrock-mantle.{region}.api.aws`) for VPC endpoints/proxies. | No |
| `AWS_BEARER_TOKEN_BEDROCK` | Short-lived bearer token for the Messages endpoint (`x-api-key` header, no SigV4). | No |
| `BEDROCK_MAX_TOKENS` | Output token limit. | No |
| `BEDROCK_TEMPERATURE` | Temperature for OpenAI models on Bedrock. | No |
| `CHATCLI_BEDROCK_CA_BUNDLE` | PEM bundle with corporate CA for TLS. Takes precedence over `AWS_CA_BUNDLE` and the global `CHATCLI_CA_BUNDLE`. | No |
| `CHATCLI_BEDROCK_INSECURE_SKIP_VERIFY` | `true` disables TLS verification (insecure, troubleshooting only). Takes precedence over the global `CHATCLI_TLS_INSECURE_SKIP_VERIFY`. | No |
| `AWS_EC2_METADATA_DISABLED` | `true` disables IMDS (prevents timeout on 169.254.169.254 outside EC2). | No |
| `CHATCLI_BEDROCK_ENABLE_IMDS` | `true` forces IMDS probe on non-EC2 machines. | No |
Bedrock **does not use an API key** — authentication uses the AWS SDK credential chain: env vars → `~/.aws/credentials` → `~/.aws/config` (SSO, assume-role) → IAM role (EC2/ECS/EKS).
**\*** At least **one** credential source is required: `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, SSO profile in `~/.aws/config`, credentials in `~/.aws/credentials`, or IAM role. For full details (SSO, proxy, inference profiles), see the [AWS Bedrock documentation](/features/bedrock).
> **\*** For OpenAI, Anthropic, and GitHub Copilot, the API key is required only if you are **not** using OAuth authentication (`/auth login`). Both methods can coexist.
***
## Agent Mode Configuration
| Variable | Description |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `CHATCLI_AGENT_ALLOW_SUDO` | Set to `"true"` to allow the agent to suggest and execute commands with `sudo`. **Use with extreme caution.** |
| `CHATCLI_AGENT_DENYLIST` | List of regex patterns (separated by `;`) to block additional commands in agent mode. |
| `CHATCLI_AGENT_CMD_TIMEOUT` | Timeout for a single command execution by the agent (default: `10m`, maximum: `1h`). |
| `CHATCLI_AGENT_PLUGIN_MAX_TURNS` | Maximum agent turn limit in `/agent`/`/coder` mode (default: `50`, maximum: `200`). |
| `CHATCLI_AGENT_PLUGIN_TIMEOUT` | Total agent plugin timeout (default: `15m`). |
### Multi-Agent (Parallel Orchestration)
| Variable | Description | Default |
| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `CHATCLI_AGENT_PARALLEL_MODE` | Enables multi-agent mode with parallel orchestration. The orchestrator LLM dispatches specialist agents in parallel. | `false` |
| `CHATCLI_AGENT_MAX_WORKERS` | Maximum number of workers (goroutines) executing agents simultaneously. | `4` |
| `CHATCLI_AGENT_WORKER_MAX_TURNS` | Maximum turns in each worker agent's mini ReAct loop. | `10` |
| `CHATCLI_AGENT_WORKER_TIMEOUT` | Timeout per individual worker agent. Accepts Go durations (e.g., `30s`, `2m`, `10m`). | `5m` |
| `CHATCLI_AGENT_PARALLEL_TOOLS` | Enables parallel execution of concurrency-safe tools **within a single agent** (read-only ops like `@read`, `@search`, `@websearch`). Distinct from `CHATCLI_AGENT_PARALLEL_MODE` (multi-agent). Off by default while in rollout. | `false` |
| `CHATCLI_AGENT_MAX_TOOL_CONCURRENCY` | Fan-out cap for the parallel tool batch within an agent. | `10` |
| `CHATCLI_AGENT_INLINE_CODE_STRICT` | For `python -c` / `node -e` / `perl -e` / `ruby -e` / `php -r` / `lua -e` invocations, treat inline source as dangerous unless proven safe (conservative mode). Default lets safe read-only one-liners through and only blocks patterns with `os.system`, `subprocess`, `socket`, `eval`, file writes, network. | `false` |
> For complete details on the multi-agent system, see the [Multi-Agent Orchestration documentation](/features/multi-agent-orchestration).
***
## Server Mode Configuration (`chatcli server`)
| Variable | Description | Default |
| :------------------------ | :---------------------------------------------------------------------- | :------ |
| `CHATCLI_SERVER_PORT` | gRPC server port. | `50051` |
| `CHATCLI_SERVER_TOKEN` | Server authentication token. Empty = no authentication. | `""` |
| `CHATCLI_SERVER_TLS_CERT` | Path to the server TLS certificate. | `""` |
| `CHATCLI_SERVER_TLS_KEY` | Path to the server TLS key. | `""` |
| `CHATCLI_GRPC_REFLECTION` | Enables gRPC reflection for debugging. **Keep disabled in production.** | `false` |
***
## Provider Fallback
| Variable | Description | Default |
| :---------------------------------- | :---------------------------------------------------------------------------------------------------------- | :-------------- |
| `CHATCLI_FALLBACK_PROVIDERS` | Comma-separated list of providers for automatic failover. E.g.: `OPENAI,CLAUDEAI,GOOGLEAI`. | `""` |
| `CHATCLI_FALLBACK_MODEL_` | Specific model per provider in the chain. E.g.: `CHATCLI_FALLBACK_MODEL_CLAUDEAI=claude-sonnet-4-20250514`. | (default model) |
| `CHATCLI_FALLBACK_MAX_RETRIES` | Retries per provider before advancing to the next in the chain. | `2` |
| `CHATCLI_FALLBACK_COOLDOWN_BASE` | Base cooldown duration after a provider failure. | `30s` |
| `CHATCLI_FALLBACK_COOLDOWN_MAX` | Maximum cooldown duration (exponential backoff). | `5m` |
> For complete details, see the [Provider Fallback documentation](/features/provider-fallback).
***
## MCP (Model Context Protocol)
| Variable | Description | Default |
| :-------------------- | :---------------------------------------------- | :---------------------------- |
| `CHATCLI_MCP_ENABLED` | Enables the MCP server manager. | `false` |
| `CHATCLI_MCP_CONFIG` | Path to the MCP server configuration JSON file. | `~/.chatcli/mcp_servers.json` |
### Files under `~/.chatcli/mcp/`
Beyond `mcp_servers.json`, the MCP subsystem manages a dedicated directory for durable state:
| File | Purpose |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.chatcli/mcp/channels.jsonl` | Durable ring of push notifications (append-only, rotates at 10 MiB to `.1`). Replayed on boot — alerts received while ChatCLI was closed remain visible |
| `~/.chatcli/mcp/channels.jsonl.1` | Single rotated historical file (rotation overwrites the previous) |
| `~/.chatcli/mcp/triggers.json` | **Opt-in** — trigger engine rules (`notify` / `confirm` / `auto`) that decide how ChatCLI reacts to channel events. See [MCP Channels](/features/mcp-channels) |
> For complete details, see the [MCP documentation](/features/mcp-integration) and [MCP Channels](/features/mcp-channels).
***
## Web Search
| Variable | Description | Default |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------- | :------ |
| `CHATCLI_WEBSEARCH_PROVIDER` | Preferred backend for `@websearch` / `/websearch`: `searxng`, `duckduckgo`, `brave`, `mojeek`, or `auto`. | `auto` |
| `SEARXNG_URL` | Root URL of the self-hosted SearxNG instance (e.g. `https://searx.internal.corp`). | — |
Backends are **keyless** (no third-party API key). DuckDuckGo is the zero-config default; self-hosted SearxNG is preferred in corporate environments. See [Web Tools](/features/web-tools) for the fallback chain and how to enable SearxNG's JSON API.
***
## Bootstrap and Memory
| Variable | Description | Default |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
| `CHATCLI_BOOTSTRAP_ENABLED` | Enables loading bootstrap files (SOUL.md, USER.md, etc.) into the system prompt. | `true` |
| `CHATCLI_BOOTSTRAP_DIR` | Directory containing bootstrap files. | `~/.chatcli/bootstrap/` |
| `CHATCLI_MEMORY_ENABLED` | Enables the structured persistent memory system. | `true` |
| `CHATCLI_MEMORY_MODE` | Memory injection mode in agent/coder: `index` (pull, digest + `@memory recall`), `full` (full push per turn) or `off`. Chat treats `index` as `full`. | `index` |
| `CHATCLI_MEMORY_MAX_SIZE` | Maximum size of rendered MEMORY.md (bytes). | `32768` |
| `CHATCLI_MEMORY_RETENTION_DAYS` | Days to retain daily notes before automatic cleanup. | `30` |
| `CHATCLI_MEMORY_MAX_FACTS` | Maximum number of facts in memory index. | `500` |
| `CHATCLI_MEMORY_RETRIEVAL_BUDGET` | Maximum memory characters injected into system prompt. | `4000` |
| `CHATCLI_SAFETY_ENABLED` | Enables configurable safety rules in the agent shell. | `false` |
> For complete details, see the [Bootstrap and Memory documentation](/features/bootstrap-memory).
***
## Skill Registry (Multi-Registry)
| Variable | Description | Default |
| :-------------------------- | :-------------------------------------------------------------------------------------------- | :------------------ |
| `CHATCLI_REGISTRY_URLS` | Additional registry URLs separated by comma. Each URL is added as an enabled custom registry. | `""` |
| `CHATCLI_REGISTRY_DISABLE` | Registry names to disable, separated by comma. E.g.: `clawhub,chatcli`. | `""` |
| `CHATCLI_SKILL_INSTALL_DIR` | Directory where skills installed via registry are saved. | `~/.chatcli/skills` |
The registry system is configured via the `~/.chatcli/registries.yaml` file (automatically created with default registries: `chatcli` and `clawhub`). The variables above serve as overrides.
> For complete details, see the [Skill Registry documentation](/features/skill-registry).
***
## Security and Control
| Variable | Description | Default |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `CHATCLI_AUTO_UPDATE` | Auto-update policy: `auto` stages updates silently in the background, `notify` shows the update hint on the welcome screen and in-session, `off` disables both. See [Auto-Update](/features/auto-update). | `notify` |
| `CHATCLI_DISABLE_VERSION_CHECK` | Disables automatic version check on startup (implies auto-update `off`). Useful for air-gapped environments or CI/CD. | `false` |
| `CHATCLI_GRPC_REFLECTION` | Enables gRPC server reflection (exposes service schema). | `false` |
### Agent Mode Security
| Variable | Description | Default |
| :---------------------------------- | :-------------------------------------------------------------------------------------------------- | :------- |
| `CHATCLI_AGENT_SECURITY_MODE` | Security mode: `strict` (allowlist only) or `permissive` (allowlist + legacy denylist as fallback). | `strict` |
| `CHATCLI_AGENT_ALLOWLIST` | Additional commands for the allowlist, separated by `;`. E.g.: `terraform;ansible;packer`. | `""` |
| `CHATCLI_AGENT_WORKSPACE_STRICT` | Restricts file reads to the current workspace. Blocks sensitive paths (`~/.ssh`, `~/.aws`, etc.). | `false` |
| `CHATCLI_AGENT_ALLOW_KUBECONFIG` | Allows kubeconfig access even with `WORKSPACE_STRICT` enabled. | `false` |
| `CHATCLI_AGENT_EXTRA_READ_PATHS` | Additional allowed read paths, separated by `;`. | `""` |
| `CHATCLI_AGENT_SOURCE_SHELL_CONFIG` | Enables sourcing shell configuration files (`~/.bashrc`, `~/.zshrc`). **Now opt-in.** | `false` |
| `CHATCLI_MAX_COMMAND_OUTPUT` | Character limit for command output before truncation. | `50000` |
### Authentication and Tokens
| Variable | Description | Default |
| :------------------------------- | :--------------------------------------------------------------------------------- | :--------------- |
| `CHATCLI_MAX_TOKEN_LIFETIME` | Maximum lifetime for OAuth/JWT tokens. Accepts Go durations (e.g., `24h`, `168h`). | `720h` (30 days) |
| `CHATCLI_JWT_SECRET` | Secret for signing server JWT tokens. | `""` |
| `CHATCLI_SESSION_ENCRYPTION_KEY` | Key for session encryption at rest (AES-256). | `""` |
### Network and Server Security
| Variable | Description | Default |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
| `CHATCLI_RATE_LIMIT_RPS` | Requests per second limit (0 = disabled). | `0` |
| `CHATCLI_BIND_ADDRESS` | Server bind address. Defaults to `127.0.0.1` (local); in Kubernetes, auto-detects `0.0.0.0` via `KUBERNETES_SERVICE_HOST`. Explicit value always takes precedence. | `127.0.0.1` / `0.0.0.0` (K8s) |
| `CHATCLI_AUDIT_LOG` | Enables security audit logging with details of each operation. | `false` |
### Plugin Security
| Variable | Description | Default |
| :--------------------------------- | :--------------------------------------------------------------------- | :------ |
| `CHATCLI_PLUGIN_VERIFY_SIGNATURES` | Requires valid Ed25519 signature to load plugins. | `false` |
| `CHATCLI_PLUGIN_TRUSTED_KEYS` | Trusted Ed25519 public keys for plugin verification, separated by `;`. | `""` |
### K8s Operator Security
| Variable | Description | Default |
| :------------------------------------ | :----------------------------------------------------------------- | :------ |
| `CHATCLI_OPERATOR_FAIL_CLOSED` | Fail-closed mode: blocks operations when the agent is unavailable. | `false` |
| `CHATCLI_OPERATOR_RESOURCE_ALLOWLIST` | Allowed K8s resources for the operator, separated by `;`. | `""` |
| `CHATCLI_OPERATOR_LOG_SCRUBBING` | Removes sensitive data (tokens, passwords) from operator logs. | `true` |
> For complete details on security, see the [Security and Hardening documentation](/features/security).
***
## Remote Client Configuration (`chatcli connect`)
| Variable | Description | Default |
| :----------------------- | :------------------------------------------------ | :------ |
| `CHATCLI_REMOTE_ADDR` | Remote server address (`host:port`). | `""` |
| `CHATCLI_REMOTE_TOKEN` | Authentication token to connect to the server. | `""` |
| `CHATCLI_CLIENT_API_KEY` | Your own API key/OAuth token, sent to the server. | `""` |
***
## K8s Watcher Configuration (`chatcli watch` / `chatcli server --watch-*`)
| Variable | Description | Default |
| :---------------------------- | :--------------------------------------------------------------------------- | :------------ |
| `CHATCLI_WATCH_DEPLOYMENT` | Name of the Kubernetes deployment to monitor. | `""` |
| `CHATCLI_WATCH_NAMESPACE` | Deployment namespace. | `"default"` |
| `CHATCLI_WATCH_INTERVAL` | Interval between data collections. Accepts Go durations (e.g., `10s`, `1m`). | `"30s"` |
| `CHATCLI_WATCH_WINDOW` | Time window of data kept in memory. | `"2h"` |
| `CHATCLI_WATCH_MAX_LOG_LINES` | Maximum number of log lines collected per pod. | `100` |
| `CHATCLI_KUBECONFIG` | Path to kubeconfig (optional, uses default if not set). | Auto-detected |