Exit Codes Explained

Exit codes are how Vibgrate CLI communicates pass or fail to scripts and CI systems. Understanding them is essential for turning a scan into a reliable quality gate. This article explains the concept and the flags that control gating, for developers automating drift checks.

Overview

Every command ends with an exit code: zero means success, non-zero means a failure or error condition. CI systems read this code to decide whether a step passed. For Vibgrate, a scan's exit code lets your pipeline stop a build when drift crosses a line you set.

Controlling pass/fail

By default a scan reports results. To make it gate — fail the step on a condition — use the gating flags.

Fail on a drift budget: the scan fails when the DriftScore exceeds the budget:

vg scan --drift-budget 60

Fail on a severity threshold: fail when findings meet or exceed a level:

npx @vibgrate/cli scan --fail-on error

When the condition is met, the command exits non-zero and your CI step fails; otherwise it exits zero and the step passes.

Using exit codes in scripts

Because the code is standard, you can branch on it in any shell or pipeline. A non-zero result short-circuits a chained command, and CI platforms mark the job red. This is what makes drift budgets and fitness functions enforceable rather than advisory.

Distinguishing failure from error

It helps to separate two cases:

• Gate failure — the scan ran fine but results crossed your threshold (e.g., over budget). This is the gate doing its job.
• Execution error — the scan couldn't complete (e.g., a misconfiguration). Treat these differently in your pipeline so a real error isn't mistaken for a drift regression.

Consult the Exit Codes reference for the exact codes and their meanings before scripting against specific values.

Related

• See the full Exit Codes reference for specific codes.
• See Drift budgets explained and Output formats explained.
• See Drift in CI vs local for end-to-end gating.