Global flags

These flags apply to every sub-command and may be placed before or after the sub-command name on the command line.

Options

Flag	Value	Description
--config	PATH	Path to a TOML config file. Overrides the ./gapline.toml layer; ~/.config/gapline/config.toml is still consulted.
--no-color		Disable ANSI colors, even when stdout is a TTY. Mutually exclusive with --force-color.
--force-color		Force ANSI colors, even when stdout is not a TTY (useful for piped terminal recorders). Mutually exclusive with --no-color.
--threads	N	Number of worker threads used by parallel validation rules. Auto-detected when omitted.

--config

By default, gapline walks a four-level lookup chain:

1. CLI flags (highest priority).
2. ./gapline.toml in the current directory.
3. ~/.config/gapline/config.toml (or %APPDATA%\gapline\config.toml on Windows).
4. Built-in defaults.

--config PATH replaces step 2 with the file you point at. Step 3 is still loaded as a lower-priority layer — local overrides still work, typed keys in the global file still apply.

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

A missing file at PATH is an error. A malformed TOML (syntax error, unknown key) is an error with the line and column of the offending token.

--no-color and --force-color

gapline prints colored terminal output by default when stdout is a TTY. When stdout is redirected or piped, colors are automatically suppressed.

Use --no-color in environments where the TTY detection is wrong or where you are capturing output into a log file from a PTY:

gapline validate -f gtfs.zip --no-color | tee run.log

Use --force-color when something downstream understands ANSI codes even though the immediate destination is a pipe — for example, less -R or a terminal recorder:

gapline validate -f gtfs.zip --force-color | less -R

--threads

--threads N caps the worker pool used by parallel validation. The default is the number of logical CPUs reported by the OS. Lowering the value is useful when running gapline alongside a memory- or CPU-intensive workload (a build, a test run, another validator).

gapline --threads 2 validate -f gtfs.zip

CRUD operations and .gl scripts are mostly single-threaded and do not benefit from a higher value. Validation is the main consumer of this flag.

Interaction with gapline.toml

Every global flag has an equivalent in [default] or [performance] sections of a config file. CLI flags always win. See reference/configuration-file for the full mapping.

See also

• Getting started / Configuration — where to put gapline.toml.
• Reference / Configuration file — every section and key.