Configuration

Trurlic requires an LLM API key only for trurlic design (Socratic conversations) and trurlic bootstrap --provider (direct bootstrap). The MCP server, CLI, and map are fully offline.

API keys

Environment variables (preferred)

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
# or
export OPENROUTER_API_KEY="sk-or-..."
# or
export GEMINI_API_KEY="AIza..."
# or
export CUSTOM_API_KEY="sk-..."
export CUSTOM_BASE_URL="http://my-server:8080/v1"

Ollama does not require an API key.

Environment variables take precedence over the config file.

Config file (fallback)

Create ~/.config/trurlic/config.toml with permissions chmod 600:

default_provider = "anthropic"
anthropic_api_key = "sk-ant-..."

On Unix, $XDG_CONFIG_HOME/trurlic/config.toml is used when XDG_CONFIG_HOME is set, falling back to ~/.config/trurlic/config.toml. On macOS, the path is ~/Library/Application Support/trurlic/config.toml. On Windows, %APPDATA%\trurlic\config.toml.

Trurlic refuses to read the config file if permissions are too open (group or world readable). This is enforced on Unix; Windows uses default ACLs.

Provider resolution

Provider resolution follows this precedence (highest wins):

1. CLI flag (-p anthropic) — explicit provider choice
2. Config file (default_provider = "anthropic") — persistent default
3. Auto-detect — if exactly one API key is available, use that provider

Auto-detection only considers Anthropic, OpenAI, and OpenRouter. The Custom, Ollama, and Gemini providers always require an explicit --provider flag (or default_provider in the config file).

If multiple keys are available among the auto-detect providers and no provider is specified, Trurlic errors with a message listing the available providers and asking you to choose with --provider.

Model selection

Model resolution follows this precedence:

1. CLI flag (-m claude-sonnet-4) — per-invocation override
2. Config file (default_model = "...") — persistent default
3. Provider default — see table below

Supported providers

Provider	Env var	Default model	Notes
anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-20250514	Aliases: claude
openai	OPENAI_API_KEY	gpt-4o	Aliases: gpt
openrouter	OPENROUTER_API_KEY	anthropic/claude-sonnet-4-20250514
gemini	GEMINI_API_KEY	gemini-2.5-flash	Aliases: google. Requires --provider.
custom	CUSTOM_API_KEY	(none — set via config or flag)	Aliases: openai-compatible. Requires --provider.
ollama	(none)	llama3.1	Aliases: local. No API key needed. Requires --provider.

Custom provider

The custom provider connects to any OpenAI-compatible API. It requires a base URL:

export CUSTOM_API_KEY="sk-..."
export CUSTOM_BASE_URL="http://my-server:8080/v1"
trurlic design auth -p custom -m my-model

Or via config file:

custom_api_key = "sk-..."
custom_base_url = "http://my-server:8080/v1"
custom_model = "my-model"

Ollama

Ollama connects to a local Ollama instance. No API key is needed. The default base URL is http://localhost:11434/v1:

trurlic design auth -p ollama -m llama3.1

Override the base URL with OLLAMA_BASE_URL or ollama_base_url in the config file.

Gemini

Google Gemini uses a dedicated client with the Gemini API:

export GEMINI_API_KEY="AIza..."
trurlic design auth -p gemini

Key security

API keys are wrapped in Zeroizing<String> and zeroed from memory on drop. Display and Debug show only the last 4 characters (…abcd). Keys never appear in logs, error messages, or .trurlic/ files.

Full config file reference

~/.config/trurlic/config.toml

# Default provider when -p is not specified and multiple keys exist.
# Values: "anthropic", "openai", "openrouter", "gemini", "custom", "ollama"
default_provider = "anthropic"

# Default model when -m is not specified.
# Overrides the provider's built-in default.
default_model = "claude-sonnet-4-20250514"

# API keys (env vars take precedence if set).
anthropic_api_key = "sk-ant-..."
openai_api_key = "sk-..."
openrouter_api_key = "sk-or-..."
gemini_api_key = "AIza..."
custom_api_key = "sk-..."

# Custom provider settings.
custom_base_url = "http://my-server:8080/v1"
custom_model = "my-model"

# Ollama settings (no API key needed).
ollama_base_url = "http://localhost:11434/v1"