Skip to content
gapline
GitHub

Exit codes

Every gapline process exits with one of five codes. CI scripts should branch on the exit code rather than parse stdout — the codes are stable across releases.

Canonical table

Section titled “Canonical table”
CodeNameMeaning
0SUCCESSThe operation completed normally. Also emitted when the user declined an interactive prompt (not an error — an explicit abort).
1COMMAND_FAILEDGeneric command failure: validation found errors, invalid --where query, unknown field in --set, primary- or foreign-key violation.
2CONFIG_ERRORMalformed gapline.toml, unknown key, type mismatch on a threshold. Configuration problems, not runtime problems.
3INPUT_ERRORI/O failure: feed file not found, archive unreadable, output path unwritable, permission denied.
4NO_CHANGESThe operation matched nothing and nothing was written. Distinct from SUCCESS so scripts can tell “update ran and changed zero records” from “update ran and changed N records”.

Emissions by command

Section titled “Emissions by command”

Not every command emits every code. The table below summarises which codes each sub-command can surface.

Command01234
validate✅✅✅✅
read✅✅✅✅
create✅✅✅✅
update✅✅✅✅✅
delete✅✅✅✅✅
run✅✅✅✅✅
rules list✅✅✅
completion✅✅

CI patterns

Section titled “CI patterns”

Only fail on validation errors

Section titled “Only fail on validation errors”
Terminal window
gapline validate -f gtfs.zip
case $? in
  0) echo "Feed is clean." ;;
  1) echo "Feed has ERROR-level findings." ; exit 1 ;;
  2|3) echo "Gapline setup issue, investigate." ; exit 1 ;;
esac

Distinguish “no matches” from a successful bulk update

Section titled “Distinguish “no matches” from a successful bulk update”
Terminal window
gapline update routes -f gtfs.zip --where "route_type=700" --set route_type=3 --confirm
case $? in
  0) echo "Routes updated." ;;
  4) echo "Nothing to update — already migrated." ;;
  *) echo "Update failed." ; exit 1 ;;
esac

GitHub Actions

Section titled “GitHub Actions”
- run: gapline validate -f gtfs.zip --min-severity error
  # Job fails automatically on exit code 1+ — no extra branching needed.

Why the split

Section titled “Why the split”

The five codes are deliberately narrow. They were chosen to answer three questions a wrapping script usually cares about:

  1. Did gapline run? (distinguishes SUCCESS/COMMAND_FAILED/NO_CHANGES from CONFIG_ERROR/INPUT_ERROR)
  2. Was the feed or the config to blame? (CONFIG_ERROR vs the rest)
  3. Did anything actually change? (NO_CHANGES vs SUCCESS on write commands)

Anything finer — “which rule failed”, “how many findings” — belongs in the structured report (--format json), not in the exit code.

See also

Section titled “See also”