# jq
jq is a lightweight and flexible command-line JSON processor. Often described as "sed for JSON," it allows parsing, filtering, transforming, and formatting JSON data directly from the terminal.
jq is essential for working with APIs, configuration files, and any JSON data in shell scripts or interactive workflows.
## Key Features
- **Filter and transform**: Extract and reshape JSON data
- **Format and pretty-print**: Make JSON human-readable
- **Query nested data**: Navigate complex JSON structures
- **Create JSON**: Generate JSON from scratch or other data
- **Stream processing**: Handle large files efficiently
- **Zero dependencies**: Single binary, works anywhere
## Basic Syntax
```bash
jq 'filter' input.json
# or
cat input.json | jq 'filter'
# or
curl api.example.com | jq 'filter'
```
## Essential Filters
### Identity and Formatting
```bash
jq '.' # Pretty-print (identity filter)
jq -c '.' # Compact output
jq -r '.name' # Raw output (no quotes)
```
### Object Access
```bash
jq '.key' # Get value of key
jq '.nested.key' # Nested access
jq '.["key-name"]' # Keys with special characters
```
### Array Operations
```bash
jq '.[0]' # First element
jq '.[-1]' # Last element
jq '.[2:5]' # Slice (indices 2-4)
jq '.[]' # Iterate all elements
jq '. | length' # Array length
```
### Filtering
```bash
jq '.[] | select(.age > 30)' # Filter by condition
jq '.[] | select(.name == "John")' # Exact match
jq '.[] | select(.tags | contains(["api"]))' # Contains
```
### Transformation
```bash
jq '.[] | {name, age}' # Select fields
jq '.[] | {userName: .name}' # Rename fields
jq 'map(.price * 1.1)' # Transform values
jq '[.[] | .name]' # Collect into array
```
### Aggregation
```bash
jq '[.[] | .price] | add' # Sum
jq 'group_by(.category)' # Group
jq 'unique_by(.id)' # Deduplicate
jq 'sort_by(.date)' # Sort
```
## Common Use Cases
### API Response Processing
```bash
curl -s api.github.com/users/octocat | jq '.login, .name'
```
### Extract All Values of a Key
```bash
jq -r '.items[].name' data.json
```
### Convert to CSV
```bash
jq -r '.[] | [.name, .email] | @csv' users.json
```
### Modify JSON
```bash
jq '.version = "2.0"' package.json
jq '.users += [{"name": "new"}]' data.json
```
### Combine with Other Tools
```bash
kubectl get pods -o json | jq '.items[].metadata.name'
aws ec2 describe-instances | jq '.Reservations[].Instances[].InstanceId'
```
## Useful Options
| Option | Description |
|--------|-------------|
| `-r` | Raw output (no quotes on strings) |
| `-c` | Compact output (one line) |
| `-s` | Slurp: read entire input as array |
| `-n` | Null input (for generating JSON) |
| `-e` | Exit with error if output is null/false |
| `--arg name value` | Pass string variable |
| `--argjson name value` | Pass JSON variable |
## References
- Official website: https://jqlang.github.io/jq/
- Manual: https://jqlang.github.io/jq/manual/
- GitHub: https://github.com/jqlang/jq
## Related
- [[JavaScript Object Notation (JSON)]]
- [[Command Line Interface (CLI)]]
- [[Shell]]
- [[Bash]]
- [[Zsh (Z Shell)]]