jq -e : Set Exit Status From the Result
The jq -e flag makes jq exit non-zero when the last output is null, false, or there was no output.
Gating a workflow step on a JSON condition needs an exit code, and -e turns a jq boolean or emptiness check into one in CI.
What it does
-e (--exit-status) sets the exit code from the last result: 0 if the last output was a value other than false or null, 1 if it was false or null, and 4 if no output was produced at all. Without -e, jq exits 0 as long as the program ran.
Common usage
# fail the step if there are no open PRs
gh api repos/cli/cli/pulls --jq 'length > 0' | jq -e . >/dev/null
# branch on a condition directly
jq -e '.draft == false' pr.json && echo "ready"
# assert a key exists
jq -e 'has("license")' repo.jsonFlags
| Exit code | Meaning with -e |
|---|---|
| 0 | Last output was truthy (not false/null) |
| 1 | Last output was false or null |
| 4 | No output was produced |
| 5 | Compile or usage error (any mode) |
In CI
Use -e so a shell && / || or a step if: can react to the JSON outcome without parsing text. Remember an empty result is exit 4, distinct from a false result at exit 1; both are non-zero so a plain test still fails the step.
Common errors in CI
A step that should pass but fails often has -e on a filter whose last output is false or null; check what the final value actually is. Conversely, a check that never fails may be emitting a truthy object instead of a boolean; end the program with a real comparison so the exit code reflects the condition.