Configuring JFrog Boost

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

1. .boost/config.toml in the current directory — a per-invocation override.
2. .boost/config.toml at the enclosing Git repository root, so a command run from a subdirectory still finds the project configuration.
3. ~/.boost/config.toml in your home directory — 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 subfolder 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:

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

[report]
usd_per_million_tokens = 5.0
co2e_kg_per_million_tokens = 0.21

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

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.

Environment Overrides

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

You can run environment variables in various ways. For example, to change the database path do the following:

• Prepend the variable to a specific command for one-time execution:
  Shell

  BOOST_DB_PATH="/tmp/custom_boost_history.db" boost go test ./...

• Export the variable to your shell environment for the current session:
  Shell

  # Set the persistent path override
  export BOOST_DB_PATH="/tmp/custom_boost_history.db"
  
  # All subsequent commands will now read/write to this new database file
  boost go test ./...
  boost report

• Add the variable inside the env block of your CI/CD workflow:

  - name: Run Tests with JFrog Boost
    run: boost go test ./...
    env:
      BOOST_DB_PATH: "${{ github.workspace }}/.boost/history.db"

Configuration Summary

Related Topics

• TOML Filters for JFrog Boost
• Token Savings with JFrog Boost
• JFrog Boost Quickstart