owlen/docs/configuration.md

# Owlen Configuration

Owlen uses a TOML file for configuration, allowing you to customize its behavior to your liking. This document details all the available options.

## File Location

By default, Owlen looks for its configuration file at `~/.config/owlen/config.toml`.

A default configuration file is created on the first run if one doesn't exist.

## Configuration Precedence

Configuration values are resolved in the following order:

1.  **Defaults**: The application has hard-coded default values for all settings.
2.  **Configuration File**: Any values set in `config.toml` will override the defaults.
3.  **Command-Line Arguments / In-App Changes**: Any settings changed during runtime (e.g., via the `:theme` or `:model` commands) will override the configuration file for the current session. Some of these changes (like theme and model) are automatically saved back to the configuration file.

---

## General Settings (`[general]`)

These settings control the core behavior of the application.

-   `default_provider` (string, default: `"ollama"`)
    The name of the provider to use by default.

-   `default_model` (string, optional, default: `"llama3.2:latest"`)
    The default model to use for new conversations.

-   `enable_streaming` (boolean, default: `true`)
    Whether to stream responses from the provider by default.

-   `project_context_file` (string, optional, default: `"OWLEN.md"`)
    Path to a file whose content will be automatically injected as a system prompt. This is useful for providing project-specific context.

-   `model_cache_ttl_secs` (integer, default: `60`)
    Time-to-live in seconds for the cached list of available models.

## UI Settings (`[ui]`)

These settings customize the look and feel of the terminal interface.

-   `theme` (string, default: `"default_dark"`)
    The name of the theme to use. See the [Theming Guide](https://github.com/Owlibou/owlen/blob/main/themes/README.md) for available themes.

-   `word_wrap` (boolean, default: `true`)
    Whether to wrap long lines in the chat view.

-   `max_history_lines` (integer, default: `2000`)
    The maximum number of lines to keep in the scrollback buffer for the chat history.

-   `show_role_labels` (boolean, default: `true`)
    Whether to show the `user` and `bot` role labels next to messages.

-   `wrap_column` (integer, default: `100`)
    The column at which to wrap text if `word_wrap` is enabled.

## Storage Settings (`[storage]`)

These settings control how conversations are saved and loaded.

-   `conversation_dir` (string, optional, default: platform-specific)
    The directory where conversation sessions are saved. If not set, a default directory is used:
    -   **Linux**: `~/.local/share/owlen/sessions`
    -   **Windows**: `%APPDATA%\owlen\sessions`
    -   **macOS**: `~/Library/Application Support/owlen/sessions`

-   `auto_save_sessions` (boolean, default: `true`)
    Whether to automatically save the session when the application exits.

-   `max_saved_sessions` (integer, default: `25`)
    The maximum number of saved sessions to keep.

-   `session_timeout_minutes` (integer, default: `120`)
    The number of minutes of inactivity before a session is considered for auto-saving as a new session.

-   `generate_descriptions` (boolean, default: `true`)
    Whether to automatically generate a short summary of a conversation when saving it.

## Input Settings (`[input]`)

These settings control the behavior of the text input area.

-   `multiline` (boolean, default: `true`)
    Whether to allow multi-line input.

-   `history_size` (integer, default: `100`)
    The number of sent messages to keep in the input history (accessible with `Ctrl-Up/Down`).

-   `tab_width` (integer, default: `4`)
    The number of spaces to insert when the `Tab` key is pressed.

-   `confirm_send` (boolean, default: `false`)
    If true, requires an additional confirmation before sending a message.

## Provider Settings (`[providers]`)

This section contains a table for each provider you want to configure. Owlen ships with two entries pre-populated: `ollama` for a local daemon and `ollama-cloud` for the hosted API. You can switch between them by changing `general.default_provider`.

```toml
[providers.ollama]
provider_type = "ollama"
base_url = "http://localhost:11434"
# api_key = "..."

[providers.ollama-cloud]
provider_type = "ollama-cloud"
base_url = "https://ollama.com"
# api_key = "${OLLAMA_API_KEY}"
```

-   `provider_type` (string, required)
    The type of the provider. The built-in options are `"ollama"` (local daemon) and `"ollama-cloud"` (hosted service).

-   `base_url` (string, optional)
    The base URL of the provider's API.

-   `api_key` (string, optional)
    The API key to use for authentication, if required.

-   `extra` (table, optional)
    Any additional, provider-specific parameters can be added here.

### Using Ollama Cloud

To talk to [Ollama Cloud](https://docs.ollama.com/cloud), point the base URL at the hosted endpoint and supply your API key:

```toml
[providers.ollama-cloud]
provider_type = "ollama-cloud"
base_url = "https://ollama.com"
api_key = "${OLLAMA_API_KEY}"
```

Requests target the same `/api/chat` endpoint documented by Ollama and automatically include the API key using a `Bearer` authorization header. If you prefer not to store the key in the config file, you can leave `api_key` unset and provide it via the `OLLAMA_API_KEY` (or `OLLAMA_CLOUD_API_KEY`) environment variable instead. You can also reference an environment variable inline (for example `api_key = "$OLLAMA_API_KEY"` or `api_key = "${OLLAMA_API_KEY}"`), which Owlen expands when the configuration is loaded. The base URL is normalised automatically—Owlen enforces HTTPS, trims trailing slashes, and accepts both `https://ollama.com` and `https://api.ollama.com` without rewriting the host.