validate

Synopsis

gapline validate [-f PATH] [--format FORMAT] [-o PATH] [--min-severity LEVEL] [--disable-rule RULE_ID...]

Description

validate runs every validation rule registered with the build against a GTFS feed and prints the findings grouped by severity. It is the main entry point for CI pipelines and cleanup workflows.

If --feed is omitted, gapline falls back to the [default] feed key of the nearest gapline.toml. The same applies to --format and --output.

Findings are emitted in five formats: colored terminal text (default), JSON, CSV, XML, or a self-contained HTML report. The process exits non-zero as soon as any ERROR-level finding is present.

Options

Flag	Short	Value	Description
`--feed`	`-f`	`PATH`	Path to the GTFS feed (a `.zip` archive or a decompressed directory). Optional when `[default] feed` is set in a config file.
`--format`		`FORMAT`	Output format: `text`, `json`, `csv`, `xml`, `html`. Defaults to `text`.
`--output`	`-o`	`PATH`	Write the report to this path instead of stdout.
`--min-severity`		`LEVEL`	Filter out findings below this level. One of `error`, `warning`, `info`. Both the listing and summary counts are filtered.
`--disable-rule`		`RULE_ID`	Disable one or more validation rules. Accepts multiple IDs after a single flag. Appends to `[validation] disabled_rules`.

Global flags are listed on reference/global-flags.

Output

While validation runs, gapline streams per-group progress bars for the seven validation stages. When the run finishes, a summary block is appended with the total counts and a PASS/FAIL status.

Without -o, every finding is printed inline above the summary, prefixed with its severity label:

[ERROR]    fk_violation — stop_id "BAD_STOP" not found in stops.txt — stop_times.txt:14203 — stop_id = BAD_STOP
[WARNING]  duplicate_route_short_name — two routes share short_name "747" — routes.txt:58 — route_short_name = 747
[INFO]     missing_shape — trip has no shape_id — trips.txt:1029 — shape_id =

With -o, findings go to the file and the console shows only the progress bars and summary:

$ gapline validate -f stm.zip -o output.txt
File Structure              [██████████████████████████████] 14/14
CSV Formatting              [██████████████████████████████] 2/2
→ Feed loaded: 847,392 rows in 14 files
Third-Party Validators      [██████████████████████████████] 6/6
Field Validation            [██████████████████████████████] 13/13
Key & Reference Validation  [██████████████████████████████] 24/24
Semantic & Logic            [██████████████████████████████] 24/24
Best Practices              [██████████████████████████████] 9/9

===================================
Summary
===================================
45 Errors — 94912 Warnings — 177074 Infos
Status: FAIL

Examples

Validate a feed

gapline validate -f gtfs.zip

Produce a JSON report for CI

gapline validate -f gtfs.zip --format json -o report.json

Stakeholder-friendly HTML report

gapline validate -f gtfs.zip --format html -o report.html

The HTML file is self-contained (CSS and JS are inlined). Open it with a double-click.

Only fail on errors

gapline validate -f gtfs.zip --min-severity error

Warnings and info-level findings are filtered out of both the listing and the summary counts.

Disable noisy rules

gapline validate -f gtfs.zip --disable-rule speed_validation coords_out_of_range

List every registered rule ID with gapline rules list. Shell completion also suggests rule IDs dynamically.

Read the feed from the config file

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

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

gapline validate -o report.json

Exit codes

Code	Meaning
`0`	Validation completed. No findings at or above the effective minimum severity.
`1`	Validation completed but the feed has `ERROR`-level findings (or any finding left after `--min-severity`).
`2`	Configuration error (malformed `gapline.toml`, unknown key, invalid threshold).
`3`	I/O error (feed not found, output path unwritable).

See concepts/exit-codes for the complete table.