jq Command Reference for CI Scripts

jq slices, filters, and transforms JSON with a small expression language.

jq is how pipelines read API responses. The two CI essentials are -r (raw strings, no quotes) and -e (exit code on null/false), which turn jq into a reliable gate.

Common flags/usage

• -r / --raw-output: emit raw strings without JSON quotes
• -e / --exit-status: exit 1 if the last output is null or false
• --arg NAME VALUE: pass a shell string as a $NAME variable safely
• -n / --null-input: build JSON from scratch with no input
• -c / --compact-output: one JSON object per line

Example

TAG=$(curl -fsS "https://api.github.com/repos/${REPO}/releases/latest" \
  | jq -r '.tag_name')
echo "Latest tag: ${TAG}"
jq -n --arg sha "${GITHUB_SHA}" '{commit: $sha}' > build-meta.json

In CI

Pipe curl -f into jq so an HTML error page never reaches the parser (otherwise you get "parse error: Invalid numeric literal"). A missing key yields null silently, so use -e to fail a gate. Never interpolate untrusted values into a filter; pass them with --arg.

Key takeaways

• -r strips JSON quotes so output is usable directly in shell variables.
• Pass shell values with --arg, never by string-interpolating into the filter.
• Use -e to make jq fail the step when a key is missing or false.

Related guides