0
# Command Line Interface
1

2
Command-line tool for querying JSON files using JSONPath expressions. The tool supports both file input and stdin processing, with glob pattern matching for multiple files and formatted output of matching values.
3

4
## Capabilities
5

6
### Main CLI Function
7

8
Entry point for the command-line interface with argument parsing and file processing.
9

10
```python { .api }
11
def main(*argv):
12
    """
13
    Main CLI function for jsonpath.py command-line tool.
14
    
15
    Parses command line arguments and processes JSON files with JSONPath queries.
16
    
17
    Parameters:
18
    - argv: tuple, command line arguments [program_name, expression, files...]
19
           If no files provided, reads from stdin
20
    
21
    Usage:
22
    jsonpath.py <expression> [files...]
23
    
24
    Examples:
25
    jsonpath.py '$.users[*].name' data.json
26
    jsonpath.py '$.*.price' *.json
27
    cat data.json | jsonpath.py '$.items[0]'
28
    """
29

30
def entry_point():
31
    """
32
    Console script entry point installed as 'jsonpath.py' command.
33
    
34
    Calls main() with sys.argv arguments.
35
    """
36
```
37

38
### File Processing Functions
39

40
Functions for processing individual JSON files and handling match output.
41

42
```python { .api }
43
def find_matches_for_file(expr, f):
44
    """
45
    Find JSONPath matches in a JSON file.
46
    
47
    Parameters:
48
    - expr: JSONPath object, compiled JSONPath expression
49
    - f: file-like object, JSON file to search
50
    
51
    Returns:
52
    list[DatumInContext]: Matching values with context
53
    
54
    Raises:
55
    json.JSONDecodeError: If file contains invalid JSON
56
    """
57

58
def print_matches(matches):
59
    """
60
    Print match values to stdout.
61
    
62
    Parameters:
63
    - matches: list[DatumInContext], matches to print
64
    
65
    Output:
66
    Prints each match value on a separate line using str() formatting
67
    """
68
```
69

70
## Command Line Usage
71

72
### Installation
73

74
The command-line tool is installed automatically with the package:
75

76
```bash
77
pip install jsonpath-rw
78
```
79

80
This creates a `jsonpath.py` console command.
81

82
### Basic Syntax
83

84
```bash
85
jsonpath.py <expression> [files...]
86
```
87

88
- `<expression>`: JSONPath expression string (required)
89
- `[files...]`: JSON files to search (optional, uses stdin if not provided)
90

91
### Usage Examples
92

93
#### Single File Query
94

95
```bash
96
# Find all user names
97
jsonpath.py '$.users[*].name' data.json
98

99
# Get first item's price
100
jsonpath.py '$.items[0].price' inventory.json
101

102
# Find all nested values
103
jsonpath.py '$..*' config.json
104
```
105

106
#### Multiple Files with Glob Patterns
107

108
```bash
109
# Search all JSON files in directory
110
jsonpath.py '$.version' *.json
111

112
# Search specific pattern
113
jsonpath.py '$.errors[*]' logs/*.json
114

115
# Multiple explicit files
116
jsonpath.py '$.status' file1.json file2.json file3.json
117
```
118

119
#### Stdin Processing
120

121
```bash
122
# Pipe JSON data
123
cat data.json | jsonpath.py '$.results[*].id'
124

125
# From curl
126
curl -s https://api.example.com/data | jsonpath.py '$.items[*].name'
127

128
# From other commands
129
echo '{"test": [1,2,3]}' | jsonpath.py '$.test[*]'
130
```
131

132
### Advanced Examples
133

134
#### Complex JSONPath Expressions
135

136
```bash
137
# Filtering with where clause
138
jsonpath.py '$.users[*] where @.active' users.json
139

140
# Union of multiple paths  
141
jsonpath.py '$.name|$.title' metadata.json
142

143
# Descendant search
144
jsonpath.py '$..price' catalog.json
145

146
# Field selection
147
jsonpath.py '$.user["first_name","last_name"]' profile.json
148
```
149

150
#### Error Handling
151

152
```bash
153
# Invalid JSONPath expression
154
jsonpath.py '$.invalid[syntax' data.json
155
# Output: Parse error at 1:15 near token syntax (ID)
156

157
# Invalid JSON file
158
jsonpath.py '$.test' invalid.json  
159
# Output: JSON decode error
160

161
# File not found
162
jsonpath.py '$.test' missing.json
163
# Output: File system error
164
```
165

166
## Built-in Help
167

168
The command-line tool includes comprehensive help information:
169

170
```bash
171
jsonpath.py --help
172
```
173

174
**Output:**
175
```
176
usage: jsonpath.py [-h] expression [file ...]
177

178
Search JSON files (or stdin) according to a JSONPath expression.
179

180
positional arguments:
181
  expression  A JSONPath expression.
182
  file        Files to search (if none, searches stdin)
183

184
optional arguments:
185
  -h, --help  show this help message and exit
186

187
Quick JSONPath reference (see more at https://github.com/kennknowles/python-jsonpath-rw)
188

189
atomics:
190
    $              - root object
191
    `this`         - current object
192

193
operators:
194
    path1.path2    - same as xpath /
195
    path1|path2    - union
196
    path1..path2   - somewhere in between
197

198
fields:
199
    fieldname       - field with name
200
    *               - any field
201
    [_start_?:_end_?] - array slice
202
    [*]             - any array index
203
```
204

205
## Output Format
206

207
The tool outputs matching values one per line using Python's default string representation:
208

209
```bash
210
# Simple values
211
jsonpath.py '$.count' data.json
212
# Output: 42
213

214
# String values  
215
jsonpath.py '$.name' data.json
216
# Output: Alice
217

218
# Complex objects
219
jsonpath.py '$.user' data.json
220
# Output: {'name': 'Alice', 'age': 30}
221

222
# Arrays
223
jsonpath.py '$.items' data.json
224
# Output: [1, 2, 3]
225

226
# Multiple matches
227
jsonpath.py '$.users[*].name' data.json
228
# Output:
229
# Alice
230
# Bob
231
# Charlie
232
```
233

234
## Integration Examples
235

236
### Shell Scripting
237

238
```bash
239
#!/bin/bash
240
# Extract version from package.json files
241
for file in */package.json; do
242
    version=$(jsonpath.py '$.version' "$file")
243
    echo "$(dirname "$file"): $version"
244
done
245
```
246

247
### Data Processing Pipeline
248

249
```bash
250
# Complex data processing pipeline
251
curl -s https://api.example.com/users | \
252
    jsonpath.py '$.data[*]' | \
253
    while IFS= read -r user; do
254
        echo "$user" | jsonpath.py '$.name'
255
    done
256
```
257

258
### Validation and Testing
259

260
```bash
261
# Validate expected structure exists
262
if jsonpath.py '$.config.database.host' config.json > /dev/null; then
263
    echo "Configuration valid"
264
else
265
    echo "Missing database host configuration"
266
    exit 1
267
fi
268
```