TOML Filters for JFrog Boost

JFrog Boost compresses command output with Go parsers for major tools and declarative TOML filters for everything else. Drop one-filter files under ~/.boost/filters/ or .boost/filters/ to teach Boost how to trim a custom script, linter, or internal CLI with no recompiling required.

Filter Locations

Boost merges filters from several locations and applies every filter selected by the command or output. Files are loaded in the following order:

1. Built-in filters shipped with Boost (make, terraform, shellcheck, and others)
2. ~/.config/boost/filters.toml (global filter, one per file)
3. .boost/filters.toml in your project folder (one filter per file)

Sources are merged, not overridden. This means a project filter does not replace a built-in with the same name. Both are loaded (keyed by name + source), and every filter whose match_command or match_output_select hits is applied in load order (built-in → global → project). To replace a built-in filter entirely, use boost filters disable on the filter and ship your own in its place.

Inside any specific directory (such as ~/.boost/filters/ or .boost/filters/) files are loaded in alphabetical order.

Create a Project Filter

Ship team filters in .boost/filters/ at the repository root. Anyone who clones the repository and runs Boost from a subdirectory or CI gets the same compression automatically.

To create a project filter:

1. Run mkdir -p .boost/filters.
2. Add one .toml file per filter. The name uses the format [filters.]. Use match_command plus a distinctive match_output_select to ensure the filter selects the correct agent pipe path.
3. Commit the file with the repository.
4. From a subdirectory, run boost filters show. The filter should appear with SOURCE=project.

Example

schema_version = 1

[filters.acme-cli]
description = "Keep errors and warnings from the internal acme-cli"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:\S*/)?acme-cli\b'
match_output_select = [
  '(?m)^acme-cli v',
]
strip_ansi = true
keep_lines_matching = [
  '^acme-cli v',
  '^Error:',
  '^Warning:',
  '^✗',
]
on_empty = "acme-cli: ok"

To confirm it loaded:

# From any subdirectory of the repo:
boost filters show | grep acme-cli
# → enabled   project     acme-cli   toml:project:acme-cli

After boost init, agent shell commands are piped through Boost automatically. For a fuller end-to-end example with before and after output, see Example 1: Custom Deploy Script.

Folder Layout

Custom filters live in a folder of one-filter files. Each file holds a single [filters.<name>] block plus its [[tests.<name>]] examples. This keeps filters independently editable. You or an agent can change one filter without touching the others.

~/.boost/filters/                 # global (this machine)
  my-personal.toml

<repo>/.boost/filters/            # project (commit with the team)
  acme-cli.toml
  deploy.toml

Global and project folder filters are picked up by the next boost process with no rebuild (unlike built-in filters, which are embedded at compile time).

Filter Fields

The following table lists supported filter fields.

Usage Notes

• Putting schema_version = 1 at the top of each filter file is recommended.
• A filter needs at least one selector: match_command for command-aware capture or match_output_select for piped hook output. Define both when the filter must work in both paths.
• Stages run in this order: strip_ansi → replace → match_output short-circuit → strip/keep lines → dedupe → collapse → head/tail → on_empty.
• Avoid using success-like on_empty messages unless empty filtered output proves successful.
• Commands without a Go or TOML filter pass through unchanged.

Filter Examples

This section contains the following examples:

• Example 1: Custom Deploy Script
• Example 2: Strip make Chatter
• Example 3: Short-Circuit on Clean Lint

Example 1: Custom Deploy Script

Your team runs ./scripts/deploy.sh after installing the Boost hook (./scripts/deploy.sh staging). The hook sends only output to Boost, so match_output_select is needed in addition to match_command. Use a distinctive output signature to avoid filtering unrelated commands.

schema_version = 1

[filters.deploy]
description = "Keep failures from deploy.sh"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:bash\s+)?(?:\S*/)?deploy\.sh\b'
# The hook pipes output to boost, so select by a distinctive output signature.
# (?m) makes ^ and $ match each line, not only the full output boundaries.
match_output_select = [
  '(?m)^Starting deployment$\n^Environment: ',
]
strip_ansi = true
keep_lines_matching = [
  '^Starting deployment$',
  '^Environment: ',
  '^\[(WARN|ERROR)\]',
  '^ERROR DETAILS:$',
  'failed readiness probe',
  '^File:$',
  '^deploy/check_health\.go:\d+$',
  '^Reason:$',
  '^connection refused',
  '^Rollback started\.\.\.$',
  '^Deployment FAILED$',
]

[[tests.deploy]]
name = "keeps failures, drops info chatter"
input = """
Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""
expected = """
Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""

Before (raw output):

Starting deployment
Environment: staging
[INFO] Loading kubeconfig from ~/.kube/config
[INFO] Using cluster gke_acme-prod_us-central1_staging
[INFO] Authenticating to Artifact Registry
[INFO] Pulling us-docker.pkg.dev/acme/payments:7.4.2
7.4.2: Pulling from acme/payments
a1b2c3d4e5f6: Already exists
b2c3d4e5f6a7: Pull complete
c3d4e5f6a7b8: Pull complete
Digest: sha256:9f8e7d6c5b4a3210fedcba9876543210
Status: Downloaded newer image for us-docker.pkg.dev/acme/payments:7.4.2
[INFO] Applying Helm chart payment-service-7.4.2
service/payment-service configured
deployment.apps/payment-service configured
configmap/payment-service-env configured
[INFO] Waiting for rollout
Waiting for deployment "payment-service" rollout to finish: 0 of 3 updated replicas are available...
Waiting for deployment "payment-service" rollout to finish: 1 of 3 updated replicas are available...
Waiting for deployment "payment-service" rollout to finish: 2 of 3 updated replicas are available...
[INFO] GET http://payment-service/healthz → 000
[INFO] retry 1/5
[INFO] GET http://payment-service/healthz → 000
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
[INFO] Streaming logs from payment-service-7f8d9c-abc12
Rollback started...
[INFO] Helm rollback to revision 183
Deployment FAILED
Environment: staging

After Boost filter:

Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Inline Tests

Each [[tests.]] block is a regression fixture: name, input (raw output), and expected (filtered output). Optional expect_match_output asserts whether match_output_select would select the filter for that input.

How to run inline tests

There is no boost filters test subcommand yet. Spot-check custom filters by piping sample output through boost. Built-in fixtures ship in the Boost repository and run under go test:

# Spot-check a custom filter: pipe sample output through boost
printf '%s\n' 'Starting deployment' 'Environment: staging' '[INFO] noise' | boost

# Built-in [[tests.*]] fixtures run in the Boost repo / CI:
go test ./internal/tomlfilter/ -run TestInlineTestDefs

Example 2: Strip make Chatter

Built-in filters use the same schema. This mirrors the shipped make filter: drop entering or leaving directory lines and blank rows.

schema_version = 1

[filters.make]
match_command = "^make\\b"
match_output_select = [
  "^make\\[\\d+\\]:",
  "^gcc ",
]
strip_lines_matching = [
  "^make\\[\\d+\\]:",
  "^\\s*$",
  "^Nothing to be done",
]
on_empty = "make: ok"

Before (raw output):

make[1]: Entering directory '/home/user/app'
gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

make[1]: Leaving directory '/home/user/app'

After Boost filter

gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

Example 3: Short-Circuit on Clean Lint

Use match_output to return a one-line summary when the tool succeeded quietly.

schema_version = 1

[filters.eslint-quiet]
match_command = "^eslint\\b"
match_output_select = [
  "problems",
]
match_output = [
  { pattern = "0 problems", message = "eslint: ok" },
]

Disabling a Filter

Use the CLI to disable a filter.

boost filters show                 # inventory with enabled/disabled status
boost filters show --enabled       # enabled filters only
boost filters disable git-status   # bare name or toml:builtin:git-status
boost filters enable git-status

Alternatively, edit ~/.boost/config.toml directly. List filter names under [filters] disabled. Those names are skipped at load time (built-ins and user/project filters alike).

After retrieve_disable_threshold retrieves events for the same capability (default 3), boost retrieve auto-appends the rolled-back filter name(s). Set the threshold to 0 to turn auto-disable off. Use boost filters enable (or clear the list) to re-enable the filters.

[filters]
disabled = ["git-status", "make"]
retrieve_disable_threshold = 3

Frequently Asked Questions

This section provides answers to frequently asked questions about TOML filters for JFrog Boost.

Related Topics

• Token Savings with JFrog Boost
• Configuring JFrog Boost
• JFrog Boost Quickstart
• JFrog Boost Overview