jq -n : Build JSON From Nothing
The jq -n flag runs the program with null as the single input, so you can build JSON entirely from arguments.
Constructing a request body or a matrix object from shell variables, with no input file, is the canonical use of -n with --arg in CI.
What it does
-n (--null-input) tells jq not to read from stdin; the program runs once with null as input. Combined with --arg and --argjson you build JSON purely from values. The input and inputs builtins can still pull from stdin on demand.
Common usage
# build a JSON body from shell vars
jq -n --arg name "$NAME" --argjson n 3 '{name: $name, count: $n}'
# assemble a matrix object
jq -nc --argjson os '["ubuntu","macos"]' '{include: ($os | map({os: .}))}'
# build an array from args
jq -n --args '[$ARGS.positional[]]' a b cFlags
| Flag | What it does |
|---|---|
| -n, --null-input | Run once with null, read no stdin |
| --arg n v | Bind a string variable $n |
| --argjson n v | Bind a parsed JSON variable $n |
| input / inputs | Pull stdin values explicitly |
In CI
Reach for -n whenever you assemble JSON from environment variables rather than transforming an existing document. Pair with --argjson for numbers, booleans, and arrays so they are not stringified.
Common errors in CI
"jq: error: $name is not defined" means you referenced a variable without a matching --arg. With -n, a program that does .field returns null because the input is null, not your data; bind the data with --argjson instead. "Cannot index null" usually means you forgot the value is null under -n.