Configuration

zo reads ~/.config/zo/config.toml. If the file is absent, built-in defaults are used.

zo +init-config

The initializer creates a commented config and ~/.config/zo/policies/default. It does not overwrite an existing config.

Compact complete example

# OPENROUTER_API_KEY takes precedence when both are set
api_key = "sk-or-v1-..."
 
default_model = "sol"
reasoning_effort = "high"
web = false
history_file = "~/.zo/history.txt"
theme = "base16-ocean.dark"
 
[inline_colors]
heading = "cyan"
inline_code = "yellow"
emphasis = "white"
prompt = "cyan"
 
[models]
fast = "google/gemini-3.7-flash"
# opus = "" # disable a built-in alias
 
[[custom_models]]
name = "reviewer"
model = "anthropic/claude-sonnet-5"
system_prompt = "Review code concisely and prioritize correctness."
reasoning_effort = "high"
 
[shell]
default_action = "ask"
allowed_shells = ["/bin/sh", "/bin/bash", "/bin/zsh"]
 
[limits]
max_input_bytes = 1048576
max_session_bytes = 4194304

Unknown fields and invalid values are rejected with a configuration error.

General settings

Field	Default	Meaning
`api_key`	unset	OpenRouter API key; `OPENROUTER_API_KEY` has priority
`default_model`	`"sol"`	Alias or direct model ID used without an override
`reasoning_effort`	effective `"high"`	Global text/chat reasoning effort
`web`	`false`	Enable server-side web search for text and chat
`history_file`	unset	Persist interactive chat input lines, not conversations
`theme`	`"base16-ocean.dark"`	Syntax-highlighting theme

Reasoning values are auto, max, xhigh, high, medium, low, minimal, and none. CLI settings override custom-model settings, which override the global value.

Models

[models] adds aliases, replaces built-in mappings, or disables a built-in with an empty string. Empty values are invalid for new aliases.

[[custom_models]] requires name and model; system_prompt and reasoning_effort are optional. Custom model names override aliases with the same name.

See Models & Customization for the built-in list and matching rules.

Rendering

Available built-in themes include:

base16-ocean.dark, base16-eighties.dark, base16-mocha.dark
Solarized (dark), Solarized (light)
InspiredGitHub, base16-ocean.light

Inline colors accept standard terminal color names, light/dark variants, gray/grey variants, or #RRGGBB. If [inline_colors] is omitted, zo chooses suitable defaults for the selected light or dark theme.

Limits

limits.max_input_bytes covers prompt text, piped STDIN, and referenced-file contents for one submitted turn. Input over the limit is rejected.

limits.max_session_bytes bounds serialized messages retained for an API request. Chat removes the oldest complete turns when necessary while keeping the system prompt and current turn. Both settings count bytes, not model tokens.

Override either value for one invocation with --max-input-bytes or --max-session-bytes.

Shell configuration

shell.default_action is allow, ask, or deny. shell.allowed_shells must contain unique absolute shell paths.

Command rules are not stored in TOML. Put them in named files under ~/.config/zo/policies/; legacy shell.always_on and shell.policy_sets configuration is rejected with migration guidance.

See Shell Tools & Policies for policy syntax, selection order, and inline tests.

Quick Start → · CLI Usage →