jq: Usage, Options & Common CI Errors
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.
What it does
jq applies a filter program to JSON input and emits JSON (or raw text with -r) on stdout. It is the standard tool for extracting fields from API responses in scripts.
Common usage
echo '{"name":"ci"}' | jq -r '.name' # -> ci (no quotes)
jq -r '.items[].id' response.json
jq '.[] | select(.active)' data.json
jq -n --arg v "${VALUE}" '{key: $v}' # safely inject a var
curl -fsS https://api/x | jq -e '.ok' >/dev/null || exit 1Options
| Flag | What it does |
|---|---|
| -r / --raw-output | Emit raw strings without JSON quotes |
| -e / --exit-status | Exit 1 if last output is null/false, 4 if no output |
| -n / --null-input | Start with null input (build JSON) |
| --arg name value | Pass a shell string as a $name variable |
| -c / --compact-output | One JSON object per line |
| -s / --slurp | Read the whole input stream into one array |
Common errors in CI
jq: error (at <stdin>:0): Cannot index string with "x" - you indexed a value that is not an object (often the input was an error string, not JSON). "parse error: Invalid numeric literal at line 1, column N" means the input was not JSON at all (an HTML error page or empty body) - pipe curl -f so failures do not reach jq. A missing key yields null silently; use -e to fail, and never interpolate untrusted values into the filter (use --arg).