jsondiff-cli

Compare two JSON files and show structural differences — additions, deletions, type changes, and value changes with colored terminal output.

Install

npm install -g jsondiff-cli

Or run directly:

npx jsondiff-cli file1.json file2.json

Usage

# Compare two files
jsondiff old.json new.json

# Output as JSON (for piping/scripting)
jsondiff --format json old.json new.json > diff.json

# Show only additions and removals
jsondiff --filter added,removed config-v1.json config-v2.json

# Compare only a specific subtree
jsondiff --path "$.dependencies" package-old.json package-new.json

# Quiet mode for CI/CD (exit code 1 if different, 0 if identical)
jsondiff --quiet a.json b.json && echo "identical" || echo "different"

# Read from stdin
cat data.json | jsondiff - expected.json

# Compact output (one line per change)
jsondiff --format compact a.json b.json

Output Example

── Added ──
  + $.dependencies.axios: "1.6.0"
  + $.scripts.test: "jest"

── Removed ──
  - $.dependencies.lodash: "4.17.21"

── Changed ──
  ~ $.version: "1.0.0" → "1.1.0"
  ~ $.dependencies.express: "4.18.0" → "4.19.0"

── Type Changed ──
  ! $.count: string → number

7 differences: 2 added, 1 removed, 2 changed, 1 type changed

Features

• Structural diff — deep comparison of nested objects and arrays
• Type change detection — catches when "5" becomes 5 or an array becomes an object
• JSONPath output — every change shows its exact location (e.g., $.config.database.host)
• Multiple formats — colored text, JSON, or compact one-liner output
• Path filtering — compare only a subtree (e.g., --path "$.dependencies")
• Type filtering — show only additions, removals, changes, or type changes
• Quiet mode — perfect for CI/CD scripts (exit code based)
• Stdin support — pipe JSON from other commands
• Programmatic API — import and use in your own Node.js code

Programmatic API

import { diff, summarize, formatText } from 'jsondiff-cli';

const changes = diff(obj1, obj2);
const summary = summarize(changes);
console.log(formatText(changes, summary));

Options

| Option | Description | |---|---| | -f, --format <type> | Output format: text, json, compact (default: text) | | --filter <types> | Comma-separated change types: added, removed, changed, type_changed | | --path <prefix> | Only show changes under this JSONPath prefix | | --no-color | Disable colored output | | -v, --verbose | Show old/new values for type changes | | -q, --quiet | No output, exit code only (1=different, 0=identical) |

Exit Codes

| Code | Meaning | |---|---| | 0 | Files are identical (or --quiet mode, no differences) | | 1 | Differences found | | 2 | Error (file not found, invalid JSON, etc.) |

License

MIT