# jq — Lightweight Command-Line JSON Processor

> jq is the essential command-line tool for processing JSON data. It lets you slice, filter, transform, and format JSON with a concise expression language — making it indispensable for working with APIs, config files, and data pipelines in the terminal.

## Install

Save as a script file and run:

# jq — Lightweight Command-Line JSON Processor

## Quick Use
```bash
# Install jq
# macOS
brew install jq

# Linux
sudo apt install jq

# Pretty-print JSON
echo '{"name":"Alice","age":30}' | jq .

# Extract a field
echo '{"name":"Alice","age":30}' | jq .name
# Output: "Alice"

# Process API response
curl -s https://api.github.com/repos/jqlang/jq | jq '{name: .name, stars: .stargazers_count}'
```

## Introduction
jq is like sed for JSON data — a command-line tool that lets you extract, transform, and manipulate JSON with a powerful expression language. In an era where every API returns JSON, jq has become an essential tool for developers, DevOps engineers, and data analysts working in the terminal.

With over 34,000 GitHub stars, jq is installed on millions of machines and is referenced in countless tutorials, scripts, and CI/CD pipelines. Its expression language is concise yet powerful enough to handle complex data transformations.

## What jq Does
jq reads JSON input (from stdin, files, or pipes), applies transformation expressions, and outputs the result. It can extract fields, filter arrays, reshape objects, perform calculations, and format output — all without writing a full script in Python or JavaScript.

## Architecture Overview
```
[Input JSON]
stdin, file, or pipe
        |
   [jq Expression]
   Filters, selects,
   transforms data
        |
   [jq Parser & Evaluator]
   Lexer -> Parser -> Bytecode
   -> Stack-based VM
        |
[Output]
Formatted JSON,
raw text, or TSV

[Expression Types]
.field          Select field
.[]             Iterate array
| pipe           Chain filters
select(cond)    Filter
map(expr)       Transform array
group_by(.key)  Group
sort_by(.key)   Sort
```

## Self-Hosting & Configuration
```bash
# Common jq recipes

# Pretty-print a file
jq . data.json

# Extract nested fields
echo '{"user":{"name":"Alice","address":{"city":"NYC"}}}' | jq .user.address.city

# Filter array elements
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | jq '.[] | select(.age > 27)'

# Transform array
echo '[{"name":"Alice","score":95},{"name":"Bob","score":87}]' | jq '[.[] | {student: .name, grade: .score}]'

# Count items
echo '[1,2,3,4,5]' | jq length

# Unique values
echo '["a","b","a","c","b"]' | jq unique

# Group and aggregate
cat sales.json | jq 'group_by(.region) | map({region: .[0].region, total: map(.amount) | add})'

# Convert JSON to CSV
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | jq -r '.[] | [.name, .age] | @csv'

# Merge JSON objects
jq -s '.[0] * .[1]' defaults.json overrides.json

# Process API pagination
curl -s "https://api.example.com/items?page=1" | jq '.items[] | {id, name, status}'
```

## Key Features
- **JSON Parsing** — read and pretty-print any JSON data
- **Field Selection** — extract nested values with dot notation
- **Array Operations** — filter, map, sort, group, flatten, and unique
- **Object Manipulation** — construct, merge, and reshape objects
- **String Functions** — split, join, test (regex), sub, gsub
- **Math Operations** — add, min, max, floor, ceil, and more
- **Output Formats** — JSON, raw text, CSV via @csv, TSV via @tsv
- **Streaming** — process large files without loading entirely into memory

## Comparison with Similar Tools
| Feature | jq | yq | fx | gron | Miller |
|---|---|---|---|---|---|
| Input Format | JSON | YAML + JSON | JSON | JSON | CSV + JSON |
| Language | jq expressions | jq-like | JS | Grep-friendly | Miller verbs |
| Learning Curve | Moderate | Low (if know jq) | Low | Very Low | Moderate |
| Power | High | High | High | Low | High |
| Streaming | Yes | Yes | No | No | Yes |
| Best For | JSON processing | YAML + JSON | Interactive | Searching | Tabular data |

## FAQ
**Q: How do I learn jq expressions?**
A: Start with ".field" for extraction, ".[]" for array iteration, and "| pipe" for chaining. The jq playground (jqplay.org) lets you experiment interactively.

**Q: Can jq handle large files?**
A: Yes. Use --stream flag for very large files to process them incrementally without loading everything into memory.

**Q: How do I use jq in shell scripts?**
A: Use -r for raw output (no quotes): result=$(echo $json | jq -r .name). Use -e for exit codes based on output (useful in conditionals).

**Q: What is yq?**
A: yq is "jq for YAML" — it uses the same expression language but works with YAML files. Essential for processing Kubernetes manifests and Docker Compose files.

## Sources
- GitHub: https://github.com/jqlang/jq
- Documentation: https://jqlang.github.io/jq/manual
- Playground: https://jqplay.org
- Created by Stephen Dolan
- License: MIT

---
Source: https://tokrepo.com/en/workflows/f8b7c935-3712-11f1-9bc6-00163e2b0d79
Author: Script Depot