> ## 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](https://docs.bronto.io/cli/getting-started/authentication.md#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.

Most commands refuse a profile that has neither a section in the user config file nor a
stored key, and exit with `profile_not_found` (exit 4), so a typo such as `--profile p2x`
doesn't quietly fall back to the default region. `bronto auth login`, `bronto config`
commands, and any command given a key through `--api-key` or `BRONTO_API_KEY` accept a new
profile name.

`config set` only accepts the keys in the table below, and checks the value before
writing it: a typo such as `timout`, `timeout abc` or `region EU` fails with an exit code
of 2 and leaves the file unchanged. If the file already holds an invalid value (for
example from a hand edit), other commands fail with `config_invalid_timeout`,
`config_invalid_max_retries` or `config_invalid_region`, but `bronto config list`, `get`
and `set` still work, so you can repair it:

```sh theme={"dark"}
bronto config set timeout 30
```

To clear a setting, set it to an empty value. The CLI then falls back to the next source
or the default, for example the region's API URL:

```sh theme={"dark"}
bronto config set base_url ''
```

`config set` changes only the value on that key's line and keeps a comment at the end of
it. Other comments and keys the CLI doesn't use stay as they are. If the file uses TOML syntax the line edit can't handle safely, such as
inline tables, the CLI rewrites the whole file instead: every key is kept, but comments
are lost.

## 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`](https://docs.bronto.io/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](https://docs.bronto.io/cli/reference/environment-variables.md) 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. Values can be strings
or plain numbers (`timeout = 60`), here and in a project file:

```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](https://docs.bronto.io/cli/getting-started/authentication.md#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.

A `profile` in a project file switches commands to that profile's stored key and
`base_url`, which may point at a different account than you expect. Each command that uses
it says so on stderr, unless you pass `--quiet`:

```text theme={"dark"}
Using profile "prod" from /home/me/src/checkout/.bronto.toml.
```

`--profile` and `BRONTO_PROFILE` take precedence over the project file.

> [!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.


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