> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bronto.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Config files and profiles

> Where the bronto CLI reads its settings, how flags, environment variables, and files take precedence, and how profiles keep accounts apart.

You rarely need to edit a config file by hand: `bronto auth login` writes the region, and
`bronto config set` writes everything else. This page covers what is stored where, and
which value wins when several sources disagree.

## Precedence

Each setting comes from the first of these sources that has a value:

| Order | Source | Example |
| - | - | - |
| 1 | command-line flags | `--region us`, `--output json` |
| 2 | environment variables | `BRONTO_REGION=us` |
| 3 | project file `.bronto.toml` | `region = "us"` |
| 4 | user config file, active profile section | `[profiles.prod]` |
| 5 | built-in defaults | region `eu` |

The API key is resolved separately: `--api-key`, then `BRONTO_API_KEY`, then the keychain.
It's never read from a file (see [Authentication](/cli/getting-started/authentication#where-the-key-comes-from)).

## See what's in effect

`bronto config list` shows every resolved value and where it came from (`flag`, `env`,
`project`, `user`, `default`, or `keychain`). The API key is masked.

```console theme={"dark"}
$ bronto config list
KEY         VALUE                           SOURCE
api_key     bronto_d…                       env
base_url    https://api.eu.bronto.io        env
ingest_url  https://ingestion.eu.bronto.io  env
region      eu                              env
```

Here everything comes from `BRONTO_*` environment variables.

`bronto config get <key>` prints one value. It fails with `config_unknown_key` if the key
has no value from any source.

```sh theme={"dark"}
bronto config get region
```

## Change a setting

`bronto config set <key> <value>` writes to the user config file, in the active profile's
section:

```sh theme={"dark"}
bronto config set default_dataset prod/checkout-service
bronto config set output json
bronto config set timeout 60 --profile staging
```

Use `--profile <name>` to write to a profile other than the active one.

## Settings

| Key | Env variable | Default | Purpose |
| - | - | - | - |
| `region` | `BRONTO_REGION` | `eu` | region slug, `eu` or `us` |
| `base_url` | `BRONTO_BASE_URL` | from region | full API base URL, for staging or local instances |
| `ingest_url` | `BRONTO_INGEST_URL` | from region | ingestion endpoint for `bronto send` |
| `output` | | table at a terminal; JSON or JSONL piped | default output format |
| `default_dataset` | | | dataset used when you omit `-d` |
| `timeout` | `BRONTO_TIMEOUT` | `30` | HTTP timeout in seconds |
| `max_retries` | `BRONTO_MAX_RETRIES` | `2` | retries for idempotent requests on 429, 502, 503, and 504 |
| `app_url` | `BRONTO_APP_URL` | from region | web app URL for `search --url` and `--open` |
| `org_id` | `BRONTO_ORG_ID` | from the API | org for web-app links |
| `ask_url` | `BRONTO_ASK_URL` | | chat-completions endpoint for [`bronto ask`](/cli/guides/ask) |
| `ask_model` | `BRONTO_ASK_MODEL` | `gpt-4o-mini` | model for `bronto ask` |
| `profile` | `BRONTO_PROFILE` | `default` | which profile to use |

Two secrets are environment-only and can't be set with `config set`: `BRONTO_API_KEY`
and `BRONTO_ASK_API_KEY`. [Environment variables](/cli/reference/environment-variables) lists
every variable the CLI reads.

## The user config file

The file is `bronto/config.toml` inside your OS's user config directory:

| OS | Path |
| - | - |
| macOS | `~/Library/Application Support/bronto/config.toml` |
| Linux | `$XDG_CONFIG_HOME/bronto/config.toml`, usually `~/.config/bronto/config.toml` |
| Windows | `%AppData%\bronto\config.toml` |

Set `BRONTO_CONFIG_DIR` to use a different parent directory. The REPL history and the
fallback credentials file live in the same `bronto/` directory.

The file holds a default profile name and one section per profile:

```toml theme={"dark"}
default_profile = "prod"

[profiles.prod]
region = "eu"
default_dataset = "prod/checkout-service"

[profiles.staging]
base_url = "https://api.staging.example.com"
ingest_url = "https://ingestion.staging.example.com"
default_dataset = "staging/checkout-service"
```

## Profiles

A profile bundles settings and its own stored API key. Select one per command with
`--profile <name>` or `BRONTO_PROFILE`, or change the default with `bronto auth switch`:

```sh theme={"dark"}
bronto auth login --profile staging   # store a key for staging and make it the default
bronto auth switch prod               # back to prod
bronto search "status >= 500" --profile staging --since 1h
```

[Authentication](/cli/getting-started/authentication#profiles) covers logging in to and out
of profiles.

## Project files

A `.bronto.toml` in your working directory, or in any directory above it, applies to
every command run there. It's a flat TOML file with no profile sections. Use it to pin a
repository to its dataset:

```toml theme={"dark"}
default_dataset = "prod/checkout-service"
output = "json"
```

A project file can set `profile`, `region`, `output`, `default_dataset`, `timeout`, and
`max_retries`. Nothing else is read from it.

<Warning>
  **Why project files are restricted**

  The CLI finds `.bronto.toml` by walking up from wherever you are, so it might belong to a
  repository you just cloned. To keep such a file from sending your API key elsewhere, it
  can't set `base_url`, `ingest_url`, `ask_url`, or `app_url`, and `region` must be a plain
  slug like `eu` (lowercase letters, digits, dashes). A project file that contains `api_key`
  is rejected with an error.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.