jq: Command-line Tool for Handling JSON Data

Overview
jq is a command-line utility for processing JSON data, similar in functionality to sed and awk but specifically designed for JSON, making it extremely powerful for parsing, filtering, and formatting JSON data.

Usage

jq [options] <jq filter> [file...]
jq [options] --args <jq filter> [strings...]
jq [options] --jsonargs <jq filter> [JSON_TEXTS...]

Description
jq processes JSON input by applying specified filters to JSON text, outputting the result in JSON format to standard output. The simplest filter is . (dot), which outputs the JSON input as-is (with formatting adjustments and IEEE 754 numeric representation). For more complex filters, refer to the jq(1) manual or jq’s official documentation.

Options

• -c: Compresses output, removing whitespace and newlines to produce compact JSON.
• -r: Outputs raw format without quotes, useful for string values.
• -R: Reads raw strings instead of JSON text.
• -s: Slurps all input JSON objects into a single array.
• -n: Uses null as the input, often used to create new JSON objects without reading input.
• -e: Sets exit status based on output.
• -S: Sorts keys in output JSON objects.
• -C: Colors JSON output (enabled by default).
• -M: Monochrome mode, disables JSON coloring.
• --tab: Indents using tabs.
• --arg a v: Sets $a to value <v>.
• --argjson a v: Sets shell variable $a to JSON value <v>.
• --slurpfile a f: Sets $a as an array from JSON data in file <f>.
• --rawfile a f: Sets $a to the raw content of file <f>.
• --args: Treats remaining arguments as string parameters, not files.
• --jsonargs: Treats remaining arguments as JSON parameters.
• --: Stops processing options.

Arguments can also be accessed using $ARGS.named[] for named parameters or $ARGS.positional[] for positional parameters.

Parameters

• file...: One or more files.
• strings...: One or more strings.
• JSON_TEXTS...: One or more JSON strings.

Filters

• .: Refers to the current JSON object, used to access fields.
• []: Accesses elements in an array.
• |: Passes output from one expression as input to the next.
• {}: Creates a new JSON object.
• [] | .field: Traverses an array and extracts specific fields from each object.

Operators and Built-in Functions
Includes common operators (+, -, *, /, %) and functions like length, has, map, select, unique, min, and max. String functions include split, join, startswith, and endswith. Regex and mathematical functions are also available, such as test, match, sqrt, and range.

Examples

1 Basic Examples

Compact JSON output by removing whitespace and newlines:

echo '{"name": "Alice", "age": 30}' | jq -c .

Output:
{"name":"Alice","age":30}

Raw output without quotes, typically for string values:

echo '{"name": "Alice", "age": 30}' | jq -r .name

Output:
Alice

Combine all input JSON objects into an array:

$ echo '{"name": "Alice", "age": 30}{"name": "Bob", "age": 25}{"name": "Charlie", "age": 35}' | jq -s .

Output:

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "age": 25 },
  { "name": "Charlie", "age": 35 }
]

Passing shell variables to jq as JSON variables:

name="Alice"
echo '{}' | jq --arg name "$name" '{name: $name}'

Output:
{ "name": "Alice" }

2 Filter Examples

Access an element in a JSON array:

echo '[{"name": "Alice"}, {"name": "Bob"}, {"name": "Charlie"}]' | jq '.[1]'

Output:

{ "name": "Bob" }

Create a new JSON object with defined key-value pairs:

jq -n '{name: "Alice", age: 30}'

Output:

{ "name": "Alice", "age": 30 }

Traverse an array and extract a specific field from each object:

echo '[{"name": "Alice"}, {"name": "Bob"}, {"name": "Charlie"}]' | jq '.[].name'

Output:

"Alice"
"Bob"
"Charlie"

3 Operators, Control Statements, and Built-in Functions

Use conditional expressions to modify output:

echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}]' | jq 'map(if .name=="Alice" then "yes" else "no" end)'

Output:

[ "yes", "no", "no" ]

4 jq Scripts

Save complex jq commands in a .jq file and execute them:

Create a file script.jq with:

map(select(.age > 28) | {name: .name, status: (if .age < 35 then "young" else "mature" end)})

Run the script:

echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}]' | jq -f script.jq

Output:

[
  { "name": "Alice", "status": "young" },
  { "name": "Charlie", "status": "mature" }
]

Alternatively, save JSON data to a file and filter it:

$ echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}]'>input.json
$ jq -f script.jq input.json

Output:

[
  { "name": "Alice", "status": "young" },
  { "name": "Charlie", "status": "mature" }
]