json-compare-cli

Show the structural diff between two JSON files — added, removed, and changed keys highlighted in color. Zero npm dependencies, pure Node.js.

Install

npm install -g json-compare-cli

Usage

json-diff a.json b.json

Options

| Flag | Description | |------|-------------| | --keys-only | Show only which keys changed (not values) | | --added | Show only added keys/values | | --removed | Show only removed keys/values | | --changed | Show only changed values | | --json | Machine-readable JSON output | | --no-color | Disable color output | | -v, --version | Print version | | -h, --help | Show help |

Stdin support

Read one file from stdin using -:

cat updated.json | json-diff - original.json

Output Format

Comparing: a.json → b.json

  + name          "old-app" → "new-app"
  + version       "1.0.0" → "2.0.0"
  - removed_key   "value" (removed)
  + added_key     (added) "hello"
  ~ dependencies  object changed (3 → 5 keys)

5 differences (1 added, 1 removed, 3 changed)

• + green — added
• - red — removed
• ~ yellow — changed

JSON output (--json)

json-diff a.json b.json --json | jq '.differences'

{
  "comparing": { "from": "a.json", "to": "b.json" },
  "summary": { "total": 3, "added": 1, "removed": 1, "changed": 1 },
  "differences": [
    { "path": "name", "type": "changed", "from": "old-app", "to": "new-app" },
    { "path": "version", "type": "added", "to": "2.0.0" },
    { "path": "config.timeout", "type": "removed", "from": 30 }
  ]
}

Exit Codes

| Code | Meaning | |------|---------| | 0 | Files are identical | | 1 | Differences found | | 2 | Error (invalid JSON, missing file, bad args) |

Examples

# Basic diff
json-diff package.json package-lock.json

# Show only added and removed keys
json-diff a.json b.json --added --removed

# Keys only (no values shown)
json-diff a.json b.json --keys-only

# Machine-readable output
json-diff a.json b.json --json > diff.json

# Pipe from stdin
curl https://api.example.com/config | json-diff - local-config.json

# Use in CI — exit 1 if JSON changed
json-diff expected.json actual.json || echo "JSON mismatch!"

Features

• Recursive structural diff of nested objects and arrays
• Full dot-notation path tracking (e.g., dependencies.lodash)
• Array element diffing with index paths (e.g., items[2])
• Color output with --no-color for CI pipelines
• Stdin support for piping from curl, cat, etc.
• Zero npm dependencies — pure Node.js standard library only

License

MIT © chengyixu