Configuration

Configuration

🌍 English · Polski · Français · Deutsch · 中文

ECLI is configured via a single TOML file. Defaults are sane — most users only edit the AI provider section and theme.

Where the config lives

Platform	Path
Linux / FreeBSD	~/.config/ecli/config.toml
macOS	~/Library/Application Support/ecli/config.toml
Windows	%APPDATA%\ecli\config.toml

You can override with --config /path/to/config.toml on the command line, or via the ECLI_CONFIG environment variable:

ECLI_CONFIG=/tmp/test-config.toml ecli

Precedence

When the same setting is defined in multiple places, ECLI applies (highest priority first):

1. Command-line flags (--theme dark)
2. Environment variables (ECLI_THEME=dark)
3. User config (~/.config/ecli/config.toml)
4. Built-in defaults

First-launch generation

On first launch, ECLI creates a default config with inline comments explaining every key. You can re-generate it any time:

ecli --print-default-config > ~/.config/ecli/config.toml

Schema overview

The config is divided into named sections:

[editor]      # tab size, line endings, auto-save
[ui]          # theme, panel widths, status bar
[keybindings] # custom key mappings (overrides defaults)
[ai]          # AI provider selection
[ai.openai]   # per-provider settings
[ai.anthropic]
[ai.ollama]
[ai.huggingface]
[git]         # git integration behavior
[lsp]         # language server preferences
[linters]     # linter selection per language
[panels]      # which panels are enabled

Full reference with every key and type: docs/config/config-schema.md.

Most common edits

Change theme

[ui]
theme = "dark"   # or "light", "solarized-dark", "monokai", "nord"

Themes ship with ECLI. To create a custom theme, see Themes & Customization.

Set AI provider

[ai]
default_provider = "anthropic"   # one of: openai, anthropic, ollama, huggingface, none

[ai.anthropic]
api_key = "sk-ant-..."
model = "claude-sonnet-4-5"
max_tokens = 4096

Keys can also come from environment variables — see AI Setup for the full matrix.

Tab width

[editor]
tab_width = 4
use_spaces = true   # expand tab to spaces

Line endings

[editor]
line_ending = "lf"   # or "crlf", "auto" (detect from file)

Disable autosave

[editor]
autosave = false

Enable Ruff for Python

[linters]
python = "ruff"   # default; alternatives: pylint, flake8, none

Minimal working config

If you want to start from scratch:

[editor]
tab_width = 4
use_spaces = true

[ui]
theme = "dark"

[ai]
default_provider = "none"

[git]
auto_fetch = false

[lsp]
enabled = true

Drop this in your config path and ECLI will run.

Migration

When ECLI bumps the config schema (rare), it migrates automatically and backs up the old config to config.toml.bak. See config-migration-policy for migration semantics.

Per-project config (optional)

ECLI looks for .ecli.toml in the current working directory. Settings there override the user config for that project only.

Example .ecli.toml:

[editor]
tab_width = 2          # this project uses 2-space indent

[linters]
python = "pylint"      # this project standardizes on pylint

Validating your config

ecli --check-config
# Returns exit 0 on success, prints errors otherwise.

This is also run automatically on every launch — a malformed config falls back to defaults with a warning.

See also

• AI Setup — full per-provider configuration
• Themes & Customization — visual customization
• Keybindings — customizing shortcuts
• docs/config/config-schema.md — every option documented