TOML Filters

Where filters load

Boost merges filters from several locations and applies every filter selected by the command or output. Files within a folder load in sorted (deterministic) order.

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

Sources are merged, not overridden. A project filter does not replace a built-in with the same name — both load (keyed by name + source), and every filter whose match_command or match_output_select hits is applied in load order (builtin → global → project). To replace a built-in, boost filters disable its name and ship your own.

Folder layout (one filter per file)

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 — an agent (or you) can tune one filter without touching the others.

~/.boost/filters/
  git-status.toml      # [filters.git-status] + [[tests.git-status]]
  my-deploy.toml       # [filters.my-deploy] + [[tests.my-deploy]]

Folder filters in ~/.boost/filters/ are picked up by the next boost process with no rebuild (unlike built-in filters, which are embedded at compile time).

Selectors & common fields

Every filter needs at least one selector. The fields below show up in almost every example; the full glossary is at the bottom of this page.

Regex flavor

All patterns use Go's regexp package (RE2 syntax) — not PCRE. No backreferences or lookbehind. Multiline ^/$ need the (?m) flag when matching against the full output. See regexp/syntax.

Example: custom deploy script

Your team runs ./scripts/deploy.sh after installing the Boost hook. 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
"""

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

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.<name>]] 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 them

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 repo 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: strip make chatter

Built-in filters use the same schema. This mirrors the shipped make filter: drop entering/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"

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'

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

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

Prefer the CLI:

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

Or edit ~/.boost/config.toml directly — list filter names under [filters] disabled. Those names are skipped at load time (builtins and user/project filters alike). After retrieve_disable_threshold retrieve 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.

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

Filter fields

Put schema_version = 1 at the top of each filter file (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 order: strip ANSI → replace → match_output short-circuit → strip/keep lines → dedupe → collapse → head/tail → on_empty. Avoid success-like on_empty messages unless empty filtered output proves success. Commands without a matching filter pass through unchanged. See the full reference in docs/TOML_FILTERS.md on GitHub.