Configuring JFrog Boost

All JFrog Boost settings are optional. Boost reads settings from .boost/config.toml and from environment variables. Use project-level config for team defaults, global config for personal preferences, and environment variables for one-off runs.

Where Boost Looks for Configuration

Boost reads the first config.toml it finds, checking these locations in order:

.boost/config.toml in the current directory. Use this file as a per-invocation override.
.boost/config.toml at the enclosing Git repository root, so a command run from a subdirectory still finds the project configuration.
~/.boost/config.toml in your home directory. This is the global fallback that boost init writes.

A legacy boost.config.toml in any of those directories is still read for backward compatibility, but .boost/config.toml takes precedence.

When run from a subdirectory inside a monorepo, Boost defaults to using the configuration file at the repository root. However, if you place a .boost/ folder in your current working directory, Boost will detect it first and use it to override both repository-wide and global settings.

Configuration and Data Directories

Configuration directory: Settings live under .boost/ as config.toml.

Data directory: Runtime data, which includes the history.db SQLite database, update-check cache, and tee logs, lives in the operating system data directory:

Platform	Data directory
macOS	`~/Library/Application Support/boost/`
Linux	`$XDG_DATA_HOME/boost/` or `~/.local/share/boost/`
Windows	`%LOCALAPPDATA%\\boost\\`

Point the database elsewhere with BOOST_DB_PATH or [tracking] database_path.

Configuration Settings

Every configuration key is optional. Omit a section to keep its defaults. Top-level keys such as accept_terms are written by boost init when you accept the terms.

~/.boost/config.toml Global Defaults

accept_terms = "yes"

[hooks]
exclude_commands = ["vim", "nano"]

[tracing]
report = false                 # silence per-command stderr savings lines
upload = false                 # skip remote OTLP upload (local spans still recorded)

[report]
usd_per_million_tokens = 5.0
co2e_kg_per_million_tokens = 0.21

[filters]
disabled = []                  # filter names skipped by the engine; retrieve auto-appends
retrieve_disable_threshold = 3 # retrieves per capability_id before auto-disable; 0 = never

[mcp]
toon_format = false            # opt in to MCP JSON→TOON (also needs Unleash boost-mcp-toon-format)

[update]
auto_update = false            # only read from ~/.boost/config.toml

.boost/config.toml Project Override

A project-level .boost/config.toml only needs to contain settings that differ from the global defaults. All other settings are inherited from ~/.boost/config.toml or its built-in default.

[tracking]
database_path = "/data/ci/history.db"   # this repo's CI containers only

[report]
co2e_kg_per_million_tokens = 0.09       # this team's low-carbon region

In the example above, accept_terms, [hooks], and [tracing] report are left unset, which means this repo will use the global ~/.boost/config.toml or the built-in default settings for those keys.

Key	Purpose	Default Value
`accept_terms`	Records that you accepted Boost's terms; set by `boost init`.	unset
`[hooks] exclude_commands`	A list of terminal commands that Boost should not intercept or compress automatically when your AI tool runs them (matched on the first word's binary name). For more information, see Hook Exclusion Settings.	`[ ]`
`[tracing] report`	Controls whether Boost shows a quick summary line of how many tokens you saved after a command finishes. Set to `false` if you want Boost to operate completely silently. Is overridden by `BOOST_REPORT`.	`true`
`[tracing] upload`	Controls whether usage telemetry is uploaded to a remote server. Set to `false` to block Boost from sending telemetry metrics online using `boost sync`. Your usage history will still be saved locally on your computer. `--file` JSONL still writes.	`true`
`[tracking] database_path`	Specifies where Boost saves its local SQLite database file (`history.db`), which tracks your usage history. `BOOST_DB_PATH` takes precedence over this setting. Use this setting if you want to store your history logs in a specific folder (for example, in a specific CI/CD pipeline directory instead of the default location).	OS data dir / `history.db`
`[report] usd_per_million_tokens`	US dollars per 1M saved tokens for `boost report` dollar figures (non-negative). Boost uses this number to calculate how much money it saved you.	`5.0`
`[report] co2e_kg_per_million_tokens`	kg CO₂e avoided per 1M saved tokens for emissions estimates (non-negative). Boost uses this number to estimate your environmental impact savings.	`0.21`
`[filters] disabled`	A list of TOML built-in and user output filters you want to disable manually. `boost retrieve` auto-appends rolled-back filter names after reaching the retrieve threshold.	`[]`
`[filters] retrieve_disable_threshold`	The threshold for turning off a filter automatically if the AI assistant asks to retrieve uncompressed raw output too many times for the same command (`capability_id`). Set to `0` to never auto-disable. Read from global config.	`3`
`[mcp] toon_format`	Enables an experimental output format (TOON) for MCP responses in tools like Cursor or Claude on PostToolUse. Also requires Unleash `boost-mcp-toon-format`. Can be toggled in `boost report -w` settings.	`false`
`[update] auto_update`	Controls whether Boost automatically updates itself in the background. Set `false` to opt out of background self-updates. Read from global config only.	`true`

Hook Exclusion Settings

When Cursor, Claude Code, or Gemini CLI runs a shell command, Boost's hook rewrites supported tools to boost <cmd> so output is compressed before it reaches the agent.

To keep certain commands unwrapped, add them to [hooks] exclude_commands. Each entry is matched against the first word of the command, reduced to its binary name. For example, docker also matches /usr/bin/docker compose up.

[hooks]
exclude_commands = ["playwright", "vim", "docker"]

In this example, playwright test stays playwright test instead of becoming boost playwright test. The same list applies to boost rewrite and the Gemini and Copilot hook paths.

📘
Note
exclude_commands prevents automatic wrapping in agent hooks. It does not disable capture or filtering when someone runs boost playwright test directly.

Environment Overrides

You can use environment variables to override the settings in config.toml, which makes them handy for one-off runs.

Variable	Effect
`BOOST_DB_PATH`	Path to the SQLite history database. Overrides `[tracking] database_path`.
`BOOST_REPORT`	`0` silences the per-command stderr savings line.
`BOOST_REPORT_USD_PER_MTOK`	Override `[report] usd_per_million_tokens`.
`BOOST_REPORT_CO2E_KG_PER_MTOK`	Override `[report] co2e_kg_per_million_tokens`.
`BOOST_TEE_DIR`	Directory for raw output tee logs written on failure.
`XDG_DATA_HOME` or `LOCALAPPDATA`	Relocate the data directory (history database, caches, tee logs) on Linux or Windows.

Configuration Summary

The following table summarizes common configuration goals and the settings or variables that control them.

Goal	Mechanism
Edit settings for a project	`.boost/config.toml`
Edit settings for every project	`~/.boost/config.toml`
Agent should not wrap `playwright`, `vim`, and similar tools	`[hooks] exclude_commands`
Move the history database	`BOOST_DB_PATH`
Hide per-command savings on stderr	`[tracing] report = false` or `BOOST_REPORT=0`
Disable remote telemetry upload	`[tracing] upload = false`
Opt out of background self-updates	`[update] auto_update = false` in `~/.boost/config.toml`
Enable MCP JSON to TOON (turned off by default)	`Unleash boost-mcp-toon-format + [mcp] toon_format = true`

Frequently Asked Questions

This section provides answers to frequently asked questions about configuring JFrog Boost.

plusFAQs

Q: Where does Boost look for config.toml?

A: Boost checks .boost/config.toml in the current directory, then at the Git repository root, then ~/.boost/config.toml in your home directory. See Where Boost Looks for Configuration.

Q: How do I stop Boost from wrapping certain shell commands?

A: Add command names to [hooks] exclude_commands in config.toml. Each entry matches the first word of the command. See Hook Exclusion Settings.

Q: Which environment variables override config.toml?

A: BOOST_DB_PATH, BOOST_REPORT, BOOST_REPORT_USD_PER_MTOK, and BOOST_REPORT_CO2E_KG_PER_MTOK override matching settings in config.toml. See Environment Overrides.

Q: What is the difference between global and project config?

A: ~/.boost/config.toml sets defaults for every project. A .boost/config.toml in a repository overrides only the keys you set for that repo. See Configuration Settings.

Where Boost Looks for Configuration

Configuration and Data Directories

Configuration Settings

~/.boost/config.toml Global Defaults

.boost/config.toml Project Override

Hook Exclusion Settings

Environment Overrides

Configuration Summary

Frequently Asked Questions

Q: Where does Boost look for config.toml?

Q: How do I stop Boost from wrapping certain shell commands?

Q: Which environment variables override config.toml?

Q: What is the difference between global and project config?

Related Topics