vacuum uses a consistent set of exit codes across all commands to make CI/CD integration reliable.

Exit code contract

Code Description
0 Spec was processed successfully with no violations at or above the configured --fail-severity threshold
1 Spec was processed successfully, but violations were found at or above the --fail-severity threshold
2 The spec could not be parsed, a file was not found, flags were invalid, or another tool-level error occurred

CI/CD usage

The three-code contract makes it straightforward to build reliable pipelines:

vacuum lint api.yaml --fail-severity warn
status=$?

case $status in
  0) echo "Clean — no issues found" ;;
  1) echo "Lint violations found — review the output" ;;
  2) echo "Tool error — spec could not be loaded or parsed" ;;
esac

GitHub Actions example

- name: Lint OpenAPI spec
  run: vacuum lint api.yaml --fail-severity warn --no-style
  continue-on-error: true
  id: lint

- name: Handle lint result
  run: |
    if [ "${{ steps.lint.outcome }}" = "failure" ]; then
      echo "Lint failed — check the output above"
      exit 1
    fi

Distinguishing parse errors from violations

If your pipeline needs to handle parse errors differently from lint violations:

vacuum lint api.yaml --no-style 2>&1
status=$?

if [ $status -eq 2 ]; then
  echo "ERROR: Spec could not be parsed — check the file format"
  # alert, open an incident, etc.
  exit 2
elif [ $status -eq 1 ]; then
  echo "WARN: Lint violations found"
  # post a PR comment, etc.
  exit 1
fi