Skip to main content

Exit codes

Every vulkro and vulkro-sf command follows one contract, so a CI step can act on the exit code alone.

CodeMeaning
0Success, and no findings at or above --fail-on (or the command reports nothing that can fail, such as env or login).
1The scan completed and reported findings at or above --fail-on, or a gate or ratchet blocked, or a licence block.
2An error: bad arguments, a path that does not exist, an IO failure, a refused network call, or a crash.

A command whose --help names a different contract says so there; for example vulkro guard check follows the agent hook protocol, and vulkro guard read-outline always exits 0 so it never breaks the agent's read.

Telling a licence block from findings​

Both are exit 1. A licence block always ends stderr with this line, from either binary:

vulkro: license_required

vulkro-sf also prints vulkro-sf: license_required on the next line, for one more release. With --format json, ndjson or sarif, stdout carries an error document with error.reason = "license_required".

vulkro scan . --format sarif > vulkro.sarif 2> vulkro.err
code=$?
if [ "$code" = 1 ] && grep -q '^vulkro: license_required' vulkro.err; then
  echo "No licence on this runner: set VULKRO_ACCOUNT_TOKEN to a CI key." >&2
  exit 2
fi
exit "$code"

Errors in machine formats​

When a command asked for --format json, ndjson or sarif exits 2, stdout carries a JSON error document with an error.reason such as path_not_found, bad_arguments or internal_error, instead of being empty. The shapes and every reason are listed in Output schemas.

A scan that examined nothing​

A scan that could not examine a single source file (nothing in the tree is in a language this build reads) is never 0: it is 2 when nothing was reported, and 1 when the passes that need no language support (dependency manifests, containers, IaC, secrets) still reported findings. The scan names the file extensions it found, and --format json sets stats.unexamined_tree.

Quiet CI logs​

Exit codes never depend on what is printed. -q / --quiet keeps stderr to warnings and errors; tips and next-step hints print only on an interactive terminal and never when CI is set. --no-color, NO_COLOR or TERM=dumb turn colour off.

Last updated on