aboutsummaryrefslogtreecommitdiffstats
path: root/jgrep.1
blob: e84cfb80be8ed96143cdf7a7aff4db34e42bfe82 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
.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