0
# Command Line Interface
1
2
Full-featured command-line interface providing access to all DeepDiff functionality through terminal commands. The CLI supports file-based operations, various output formats, and extensive configuration options for comparing, searching, hashing, and manipulating Python objects.
3
4
## Installation
5
6
The CLI functionality requires the optional CLI dependencies:
7
8
```bash
9
pip install deepdiff[cli]
10
```
11
12
## Capabilities
13
14
### Deep Diff Command
15
16
Compare two objects from files or command line with extensive formatting and filtering options.
17
18
```bash { .api }
19
# Basic comparison
20
deep diff file1.json file2.json
21
22
# Compare with options
23
deep diff file1.json file2.json \
24
--ignore-order \
25
--ignore-case \
26
--ignore-type-changes \
27
--significant-digits 2 \
28
--report-type text \
29
--output-file result.json
30
31
# Compare with path filtering
32
deep diff file1.json file2.json \
33
--exclude-paths "root['timestamp']" "root['metadata']" \
34
--include-paths "root['data']"
35
36
# Compare with custom view
37
deep diff file1.json file2.json \
38
--view tree \
39
--verbose-level 2 \
40
--color-output
41
```
42
43
### Grep Command
44
45
Search for objects within files using flexible matching criteria.
46
47
```bash { .api }
48
# Basic search
49
deep grep "search_term" data.json
50
51
# Search with options
52
deep grep "pattern" data.json \
53
--case-sensitive \
54
--match-string \
55
--use-regexp \
56
--output-file results.json
57
58
# Search with path filtering
59
deep grep "value" data.json \
60
--exclude-paths "root['metadata']" \
61
--exclude-types "int" "float"
62
```
63
64
### Extract Command
65
66
Extract values from nested objects using path notation.
67
68
```bash { .api }
69
# Extract single value
70
deep extract "root['user']['name']" data.json
71
72
# Extract multiple paths
73
deep extract \
74
"root['user']['name']" \
75
"root['user']['email']" \
76
"root['settings']['theme']" \
77
data.json
78
79
# Extract with output formatting
80
deep extract "root['data']" input.json \
81
--output-file extracted.json \
82
--format json
83
```
84
85
### Patch Command
86
87
Apply delta patches to objects with backup and safety options.
88
89
```bash { .api }
90
# Apply patch to file
91
deep patch original.json delta.json
92
93
# Apply patch with backup
94
deep patch original.json delta.json \
95
--backup \
96
--output-file patched.json
97
98
# Apply patch with validation
99
deep patch original.json delta.json \
100
--validate \
101
--log-errors
102
```
103
104
## Command Options
105
106
### Global Options
107
108
Options available across all commands:
109
110
```bash { .api }
111
--help # Show help message
112
--version # Show version information
113
--output-file FILE # Write output to file instead of stdout
114
--format FORMAT # Output format (json, yaml, text)
115
--verbose # Enable verbose output
116
--quiet # Suppress non-error output
117
--color / --no-color # Enable/disable colored output
118
```
119
120
### Diff-Specific Options
121
122
```bash { .api }
123
--ignore-order # Ignore order of elements
124
--ignore-case # Ignore string case differences
125
--ignore-type-changes # Ignore type changes between compatible types
126
--ignore-numeric-type-changes # Ignore numeric type differences
127
--significant-digits N # Number of significant digits for floats
128
--exclude-paths PATH [PATH...] # Paths to exclude from comparison
129
--exclude-regex-paths REGEX [REGEX...] # Regex patterns for paths to exclude
130
--exclude-types TYPE [TYPE...] # Types to exclude from comparison
131
--include-paths PATH [PATH...] # Paths to include (exclude all others)
132
--report-type TYPE # Report type (text, tree, delta)
133
--view TYPE # View type (text, tree)
134
--verbose-level LEVEL # Verbosity level (0-2)
135
--get-deep-distance # Calculate distance metric
136
--group-by FIELD # Group similar changes
137
--math-epsilon FLOAT # Epsilon for float comparisons
138
--ignore-private-variables # Ignore private attributes
139
--ignore-string-type-changes # Ignore string type differences
140
--ignore-encoding-errors # Ignore encoding errors
141
--cache-size SIZE # LRU cache size for comparisons
142
```
143
144
### Search-Specific Options
145
146
```bash { .api }
147
--case-sensitive # Case sensitive string matching
148
--match-string # Match strings partially
149
--use-regexp # Treat search term as regular expression
150
--exclude-paths PATH [PATH...] # Paths to exclude from search
151
--exclude-regex-paths REGEX [REGEX...] # Regex patterns to exclude
152
--exclude-types TYPE [TYPE...] # Types to exclude from search
153
--include-paths PATH [PATH...] # Paths to include in search
154
--verbose-level LEVEL # Verbosity level (0-2)
155
--return-paths # Return paths instead of values
156
--strict-checking # Use strict type checking
157
```
158
159
### Extract-Specific Options
160
161
```bash { .api }
162
--default VALUE # Default value if path not found
163
--ignore-errors # Continue on path errors
164
--validate-paths # Validate path syntax before extraction
165
--multiple-paths # Extract multiple paths (default for multiple arguments)
166
```
167
168
### Patch-Specific Options
169
170
```bash { .api }
171
--backup # Create backup before applying patch
172
--validate # Validate patch before applying
173
--log-errors # Log errors during patch application
174
--dry-run # Show what would be changed without applying
175
--force # Force application even with warnings
176
--bidirectional # Enable bidirectional patch operations
177
```
178
179
## Usage Examples
180
181
### File Comparison
182
183
```bash
184
# Compare JSON files
185
deep diff config_old.json config_new.json
186
187
# Compare with specific options
188
deep diff database_v1.json database_v2.json \
189
--ignore-order \
190
--exclude-paths "root['timestamp']" "root['version']" \
191
--significant-digits 3 \
192
--output-file changes.json
193
```
194
195
### YAML and Other Formats
196
197
```bash
198
# Compare YAML files (requires PyYAML)
199
deep diff config.yaml config_new.yaml --format yaml
200
201
# Compare mixed formats
202
deep diff data.json data.yaml --format json
203
```
204
205
### Searching Data
206
207
```bash
208
# Search for specific values
209
deep grep "john@example.com" users.json
210
211
# Regex search
212
deep grep "^admin" users.json --use-regexp
213
214
# Case-insensitive partial match
215
deep grep "john" users.json --match-string --case-sensitive=false
216
```
217
218
### Extracting Values
219
220
```bash
221
# Extract user information
222
deep extract "root['users'][0]['name']" data.json
223
224
# Extract multiple fields
225
deep extract \
226
"root['config']['database']['host']" \
227
"root['config']['database']['port']" \
228
"root['config']['database']['name']" \
229
app_config.json
230
```
231
232
### Applying Patches
233
234
```bash
235
# Apply changes from diff
236
deep diff old.json new.json --output-file changes.delta
237
deep patch old.json changes.delta --output-file updated.json
238
239
# Apply with backup
240
deep patch production.json hotfix.delta --backup
241
```
242
243
### Pipeline Usage
244
245
```bash
246
# Use in shell pipelines
247
cat data.json | deep grep "error" | jq '.matched_values'
248
249
# Combine operations
250
deep diff old.json new.json | deep extract "root['values_changed']"
251
```
252
253
### Advanced Examples
254
255
```bash
256
# Complex diff with multiple options
257
deep diff \
258
production.json \
259
staging.json \
260
--ignore-order \
261
--ignore-type-changes \
262
--exclude-regex-paths ".*timestamp.*" ".*id.*" \
263
--significant-digits 2 \
264
--report-type tree \
265
--color-output \
266
--output-file production_vs_staging.diff
267
268
# Batch processing
269
for file in configs/*.json; do
270
deep diff template.json "$file" --output-file "${file%.json}.diff"
271
done
272
273
# Search and extract pipeline
274
deep grep "error" logs.json \
275
--match-string \
276
--output-file errors.json && \
277
deep extract "root['matched_values']" errors.json \
278
--output-file error_paths.json
279
```
280
281
## Input/Output Formats
282
283
### Supported Input Formats
284
285
```bash { .api }
286
# JSON files (default)
287
deep diff file1.json file2.json
288
289
# YAML files (requires PyYAML)
290
deep diff file1.yaml file2.yaml
291
292
# Python pickle files
293
deep diff file1.pkl file2.pkl
294
295
# CSV files (converted to list of dictionaries)
296
deep diff file1.csv file2.csv
297
```
298
299
### Output Formats
300
301
```bash { .api }
302
# JSON output (default)
303
deep diff file1.json file2.json --format json
304
305
# YAML output
306
deep diff file1.json file2.json --format yaml
307
308
# Plain text output
309
deep diff file1.json file2.json --format text
310
311
# Colored text output
312
deep diff file1.json file2.json --format text --color-output
313
```
314
315
## Configuration
316
317
### Environment Variables
318
319
```bash { .api }
320
export DEEPDIFF_COLOR=true # Enable colored output by default
321
export DEEPDIFF_VERBOSE=1 # Set default verbosity level
322
export DEEPDIFF_CACHE_SIZE=1000 # Set default cache size
323
export DEEPDIFF_OUTPUT_FORMAT=json # Set default output format
324
```
325
326
### Configuration File
327
328
Create a `.deepdiff.yaml` configuration file:
329
330
```yaml
331
# Default options for all commands
332
defaults:
333
color_output: true
334
verbose_level: 1
335
cache_size: 1000
336
337
# Command-specific defaults
338
diff:
339
ignore_order: false
340
significant_digits: 7
341
report_type: "text"
342
343
search:
344
case_sensitive: true
345
match_string: false
346
347
extract:
348
ignore_errors: false
349
validate_paths: true
350
```
351
352
## Types
353
354
```bash { .api }
355
# Input file types supported
356
InputFile = Union[JsonFile, YamlFile, PickleFile, CsvFile]
357
358
# Output format options
359
OutputFormat = Union['json', 'yaml', 'text', 'tree']
360
361
# Report types for diff command
362
ReportType = Union['text', 'tree', 'delta']
363
364
# View types for diff command
365
ViewType = Union['text', 'tree']
366
367
# Verbosity levels
368
VerbosityLevel = Union[0, 1, 2] # 0=quiet, 1=normal, 2=verbose
369
```