Settings & API Keys

Kolega Code keeps a small amount of state on your machine: your provider/model selection, API keys, and saved sessions.

The Settings tab

The fastest way to configure the CLI is the Settings tab in the side panel of the TUI:

1. Provider — choose your AI provider.
2. Model — choose a model for that provider.
3. Thinking effort — choose one of the effort values supported by that model.
4. API Key — paste your key (entered as a password field).
5. Save Settings — persists everything locally.

When you switch models, the thinking effort resets to the new model’s default.

A saved selection is used for all agent model roles. Existing environment variables and --provider / --model flags continue to override it — see Providers & Models for resolution order. API key environment variables are credentials only; they do not choose the active provider or model.

Where settings live

Settings are stored as JSON in your platform’s state directory, in a file named settings.json:

Platform	Default location
macOS	~/Library/Application Support/kolega-code/
Linux	$XDG_STATE_HOME/kolega-code/ (falls back to ~/.local/state/kolega-code/)
Windows	%LOCALAPPDATA%\kolega-code\

Override the location entirely with the KOLEGA_CODE_STATE_DIR environment variable, or per-command with --state-dir.

The file looks like this:

{
  "schema_version": 2,
  "active_provider": "moonshot",
  "active_model": "kimi-k2.7-code",
  "active_thinking_effort": "auto",
  "api_keys": {
    "moonshot": "sk-..."
  }
}

Keys are stored in plaintext

API keys are written to settings.json in plaintext, but the file is created with 0600 permissions (readable and writable only by your user). If you’d rather not store keys on disk at all, supply them via environment variables instead.

State directory layout

• Directorykolega-code/

  • settings.json Provider, model, thinking effort, and API keys (0600)
  • Directorysessions/

    • <session-id>.json One file per saved session

Inspecting your configuration

Use doctor to see, without exposing your key, where each value comes from:

kolega-code doctor --project .

It reports the state directory, whether Textual is installed, your stored active model, and — for the API key — whether it’s present via <ENV_VAR>, present in local settings, or missing. See doctor.