jgrep

A grep-like tool for searching JSON files by matching values against patterns.

Installation

# Install system-wide
sudo make install

# Or specify prefix
make install PREFIX=~/.local

# Uninstall
sudo make uninstall

Usage

jgrep [-e|-w] PATTERN [-p LEVEL] [-o] [--full] [-i] [-k KEY] [-K RE] [-P RE] [FILE...]

Options and file arguments can be interspersed in any order.

Options

Option	Description
`-e, --expr REGEX`	Regular expression pattern (default)
`-w, --fixed TEXT`	Plain text search (no regex)
`-p, --parent LEVEL`	Parent levels to traverse up (default: 0 = value)
`-o, --only-matching`	Output only the matched value (same as -p 0)
`--full`	Output full context: {key, value, parent, path}
`-i, --ignore-case`	Case insensitive matching
`-k, --key KEY`	Only search values under this key (exact match)
`-K, --key-expr RE`	Only search values under keys matching regex
`-P, --path-expr RE`	Only match paths matching regex (joined by .)
`-h, --help`	Show help

Examples

# Basic search - return matched values (default)
jgrep 'error' logs.json

# Get parent objects containing match
jgrep -p 1 '@test\.org' users.json

# Full context output for custom formatting
jgrep --full 'error' logs.json | jq '{key: .key, val: .value}'

# Filter by key name (exact)
jgrep -k email '@test' users.json

# Filter by key name (regex)
jgrep -K 'email|name' 'john' users.json

# Filter by path
jgrep -P 'employees\.\d+\.email' '@test' data.json

# Regex search - emails starting with 'j'
jgrep -e '^j.*@' users.json

# Plain text search - literal dots not treated as regex
jgrep -w 'config.json' data.json

# Get grandparent (2 levels up)
jgrep 'needle' -p 2 nested.json

# Case insensitive search
jgrep -i 'ERROR' logs.json

# Search multiple files
jgrep 'TODO' *.json

# Read from stdin
curl -s api.example.com/data | jgrep 'status'

How It Works

jgrep recursively searches all string values in JSON structures. By default it returns matched values. Use -p to traverse up to parent objects.

# Given nested.json:
# {"departments": [{"name": "eng", "employees": [{"email": "a@test.org"}]}]}

jgrep 'test.org' nested.json
# "a@test.org"

jgrep 'test.org' -p 1 nested.json
# {"email": "a@test.org"}

jgrep --full 'test.org' nested.json
# {"key":"email","value":"a@test.org","path":[...],"parent":"a@test.org"}

jgrep -P 'departments\.0' '@' nested.json
# Only matches in first department

Dependencies

bash
jq

License

MIT