.TH JGREP 1 "2025-01-23" "jgrep 1.0" "User Commands" .SH NAME jgrep \- search JSON files for matching values .SH SYNOPSIS .B jgrep [\fB\-e\fR|\fB\-w\fR] \fIPATTERN\fR [\fB\-p\fR \fILEVEL\fR] [\fB\-o\fR] [\fB\-\-full\fR] [\fB\-i\fR] [\fB\-k\fR \fIKEY\fR] [\fB\-K\fR \fIRE\fR] [\fB\-P\fR \fIRE\fR] [\fIFILE\fR...] .SH DESCRIPTION .B jgrep searches JSON files for string values matching a pattern and returns the matched values or containing objects. It recursively traverses all JSON structures without requiring knowledge of the schema. .PP If no FILE is given, or FILE is \-, read from standard input. .PP Options and file arguments can be interspersed in any order. .SH OPTIONS .TP .BR \-e ", " \-\-expr " " \fIREGEX\fR Treat PATTERN as a regular expression. This is the default behavior when no flag is specified. .TP .BR \-w ", " \-\-fixed " " \fITEXT\fR Treat PATTERN as plain text. Special regex characters are not interpreted. .TP .BR \-p ", " \-\-parent " " \fILEVEL\fR Number of parent levels to traverse up from the matched value. Default is 0, which returns just the matched value. Use 1 to get the immediate parent object, 2 for grandparent, etc. .TP .BR \-o ", " \-\-only\-matching Output only the matched values (equivalent to \fB\-p 0\fR). .TP .B \-\-full Output full context as JSON object with keys: key, value, path, parent. Useful for piping to jq for custom formatting. .TP .BR \-i ", " \-\-ignore\-case Case insensitive matching. .TP .BR \-k ", " \-\-key " " \fIKEY\fR Only search values under this exact key name. .TP .BR \-K ", " \-\-key\-expr " " \fIRE\fR Only search values under keys matching the given regex. .TP .BR \-P ", " \-\-path\-expr " " \fIRE\fR Only match values whose path matches the given regex. Path components are joined by dots (e.g., "departments.0.employees.1.email"). .TP .BR \-h ", " \-\-help Display help message and exit. .SH EXAMPLES .TP Search and return matched values (default): .B jgrep 'error' logs.json .TP Get parent objects containing match: .B jgrep -p 1 '@test\\.org' users.json .TP Full context for custom formatting: .B jgrep --full 'error' logs.json | jq '.key' .TP Filter by exact key name: .B jgrep -k email '@test' users.json .TP Filter by key regex: .B jgrep -K 'email|name' 'john' users.json .TP Filter by path regex: .B jgrep -P 'employees\\.\\d+\\.email' '@test' data.json .TP Regex search for emails starting with 'j': .B jgrep -e '^j.*@' users.json .TP Plain text search (dots are literal): .B jgrep -w 'config.json' data.json .TP Get grandparent objects (2 levels up): .B jgrep 'needle' -p 2 nested.json .TP Case insensitive search: .B jgrep -i 'ERROR' logs.json .TP Search multiple files: .B jgrep 'TODO' *.json .TP Read from stdin: .B curl -s api.example.com/data | jgrep 'status' .SH OUTPUT Output is newline-delimited JSON (one JSON value per line). This format is suitable for piping to other tools or further processing with jq. .PP With \fB\-\-full\fR, each line is a JSON object containing: .RS .IP \(bu 2 .B key \- the key name of the matched value .IP \(bu 2 .B value \- the matched string value .IP \(bu 2 .B path \- array of path components to the value (or parent with \fB\-p\fR) .IP \(bu 2 .B parent \- the object at the path level specified by \fB\-p\fR .RE .SH EXIT STATUS .TP .B 0 Matches were found. .TP .B 1 No matches found or error occurred. .SH DEPENDENCIES .B jgrep requires .BR jq (1) to be installed. .SH SEE ALSO .BR jq (1), .BR grep (1) .SH AUTHOR Louis Burda