Config files and profiles

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).

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.

$ 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.

bronto config get region

Change a setting

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

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`
`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 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:

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:

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 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:

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.

Why project files are restrictedThe 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.

Start here

Guides

Configuration

Extend

Help

Reference

Config files and profiles

Precedence

See what’s in effect

Change a setting

Settings

The user config file

Profiles

Project files

​Precedence

​See what’s in effect

​Change a setting

​Settings

​The user config file

​Profiles

​Project files

Precedence

See what’s in effect

Change a setting

Settings

The user config file

Profiles

Project files