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

​

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.

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:

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:

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
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. Values can be strings or plain numbers (timeout = 60), here and in a project file:

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.

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:

Using profile "prod" from /home/me/src/checkout/.bronto.toml.

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

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.