Configuration

gapline reads its settings from a TOML file. Keep a gapline.toml next to your feed and you can drop -f, --format, and --min-severity from every command. This page walks through where to put the file and what to put in it; reference / configuration file lists every accepted key.

The lookup chain

Settings resolve in four layers, highest priority first. Each layer overrides the next, so the CLI always has the last word.

Priority	Layer	Typical use
1	CLI flags (--feed, --format, --min-severity…)	One-off overrides for a single invocation.
2	./gapline.toml in the current directory	Per-project defaults — commit it alongside the feed.
3	Global user config (see paths below)	Personal preferences shared across every project.
4	Built-in defaults	What you get with no config at all.

--config PATH on the CLI replaces layer 2 with the file you point at. Layer 3 is still consulted as a lower-priority layer — local overrides still win.

Where to put the file

Linux / macOS

• Local — ./gapline.toml in the directory you run gapline from.
• Global — ~/.config/gapline/config.toml.

mkdir -p ~/.config/gapline
touch ~/.config/gapline/config.toml

Windows

• Local — .\gapline.toml in the directory you run gapline from.
• Global — %APPDATA%\gapline\config.toml.

New-Item -ItemType Directory -Force "$env:APPDATA\gapline" | Out-Null
New-Item -ItemType File -Force "$env:APPDATA\gapline\config.toml" | Out-Null

Explicit path

Point --config at any TOML file. Good for CI environments where the file lives outside the project.

gapline --config ci/gapline.ci.toml validate -f data/gtfs.zip

Minimal example

This is all most projects need. Drop a feed path and the default format, stop typing them on every command.

gapline.toml

[default]
feed   = "./data/gtfs.zip"
format = "json"

# With the config above, this runs validate on ./data/gtfs.zip and emits JSON.
gapline validate -o report.json

A more complete example

Once the project has a cadence (strict severity in CI, a couple of rules you know are noisy, specific speed thresholds for your rail feed), pin them in the config.

gapline.toml

[default]
feed   = "./data/gtfs.zip"
format = "json"

[validation]
min_severity   = "warning"
disabled_rules = ["block_id_trip_overlap"]

[validation.thresholds.speed_limits]
rail_kmh = 320
bus_kmh  = 120

[validation.thresholds.calendar]
min_feed_coverage_days       = 60
feed_expiration_warning_days = 14

[output]
show_progress = true
group_by_rule = true

The full list of accepted sections and keys is on reference / configuration file.

Error behaviour

• A missing file at any layer is silently skipped. No error, no warning — it just does not contribute to the merged config.
• A malformed file (broken TOML, unknown key) aborts with exit code 2 and a message that points to the file and the offending token. gapline deliberately refuses unknown keys so a typo in a section name does not silently pass.
• A semantically invalid value (a negative speed limit, zero calendar coverage, a transfer warning greater than the max) aborts with the same exit code and cites the specific field.

Config error in ./gapline.toml: unknown field `validattion`, expected one of `default`, `validation`, `performance`, `output`, `batch`, `experimental`

Tip

Run gapline validate --config ./gapline.toml with the config you are about to ship. If validation starts, the config is sound; if it aborts with exit code 2, the error message tells you exactly what to fix.

See also

• Configuration file reference — every section, key, type, and default.
• Global flags — --config, --no-color, --threads.
• Validating feeds — how the config is used during a real pipeline.