---
title: Configuration
description: Config file reference — network policies, OAuth profiles, and search
icon: Settings
---

Config file: `~/.config/earl/config.toml`. All sections are optional.

## File Locations

| Path                                     | Purpose               |
| ---------------------------------------- | --------------------- |
| `~/.config/earl/config.toml`             | Main configuration    |
| `~/.config/earl/templates/*.hcl`         | Global templates      |
| `./templates/*.hcl`                      | Workspace templates (override global) |
| `~/.local/state/earl/secrets-index.json` | Secret metadata index |
| `~/.cache/earl/search-index-v1.json`     | Search cache          |

## Full Example

```toml
# --- Network ---

[[network.allow]]
scheme = "https"
host = "api.github.com"
port = 443
path_prefix = "/"

[network]
allow_cli_commands = ["cargo", "git"]

[network.proxy_profiles.corp]
url = "https://proxy.corp.example.com:8080"

# --- Auth ---

[auth.profiles.github]
flow = "device_code"
client_id = "your-client-id"
token_url = "https://github.com/login/oauth/access_token"
device_authorization_url = "https://github.com/login/device/code"
scopes = ["repo", "read:org"]

# --- Search ---

[search]
top_k = 40
rerank_k = 10

[search.local]
embedding_model = "BGESmallENV15Q"
reranker_model = "JINARerankerV1TurboEn"

[search.remote]
enabled = false
# base_url = "https://search.example.com"
# api_key_secret = "search.api_key"
```

## Network Allowlist

`[[network.allow]]` restricts outbound HTTP traffic. Without any entries, all destinations are allowed. With one or more entries, requests must match at least one rule.

| Field         | Type     | Required | Description                                      |
| ------------- | -------- | -------- | ------------------------------------------------ |
| `scheme`      | `string` | Yes      | `https` or `http`                                |
| `host`        | `string` | Yes      | Exact hostname                                   |
| `port`        | `u16`    | Yes      | TCP port (usually `443`)                         |
| `path_prefix` | `string` | Yes      | Only paths starting with this prefix are allowed |

## CLI Command Allowlist

`network.allow_cli_commands` restricts which executables CLI-protocol templates can invoke. Templates using `protocol = "cli"` will fail if their command isn't listed.

```toml
[network]
allow_cli_commands = ["cargo", "git", "npm"]
```

## Proxy Profiles

Named proxy profiles under `[network.proxy_profiles.<name>]`. Templates reference them via `transport.proxy_profile`.

```toml
[network.proxy_profiles.corp]
url = "https://proxy.corp.example.com:8080"
```

## OAuth Profiles

Define profiles under `[auth.profiles.<name>]` and reference them from templates via `auth.kind = "oauth2_profile"`. See [Auth](/docs/auth) for flow details.

| Flow                 | Required Fields                         |
| -------------------- | --------------------------------------- |
| `auth_code_pkce`     | `token_url`, `authorization_url`        |
| `device_code`        | `token_url`, `device_authorization_url` |
| `client_credentials` | `token_url`                             |

All flows require `client_id`. Optional fields: `client_secret_key`, `redirect_url`, `scopes`, `issuer`, `use_auth_request_body`.

## Search

Controls the semantic search engine used by `earl templates search`.

| Key                            | Default                | Description                          |
| ------------------------------ | ---------------------- | ------------------------------------ |
| `search.top_k`                 | `40`                   | Candidates retrieved from embeddings |
| `search.rerank_k`              | `10`                   | Results returned after reranking     |
| `search.local.embedding_model` | `BGESmallENV15Q`       | Local embedding model name           |
| `search.local.reranker_model`  | `JINARerankerV1TurboEn`| Local reranker model name            |
| `search.remote.enabled`        | `false`                | Use a remote search service          |
| `search.remote.base_url`       | —                      | Remote service URL                   |
| `search.remote.api_key_secret` | —                      | Secret key for the remote API        |
| `search.remote.timeout_ms`     | `10000`                | Request timeout in milliseconds      |

<Callout type="info">
  Run `earl doctor` to verify your configuration. See [Troubleshooting](/docs/troubleshooting) for common errors.
</Callout>
