Compare JSON

@compare-json/cli

A command-line tool and MCP server for comparing JSON files or strings. Built on top of @compare-json/core.

Online Playground

Try it out at https://comparejson.com

Installation

# npm
npm install -g @compare-json/cli

# yarn
yarn global add @compare-json/cli

# pnpm
pnpm add -g @compare-json/cli

CLI

Quick Start

# View help
compare-json --help

# Compare two JSON strings
compare-json '{"a":1}' '{"a":2}'

# Compare two JSON files
compare-json file1.json file2.json

# Output as JSON format
compare-json file1.json file2.json --json-export

# Save output to file
compare-json file1.json file2.json -o output.txt

# Start the MCP server (stdio transport)
compare-json --mcp

Usage

compare-json [base] [contrast] [options]

Each positional argument can be either an inline JSON string or a path to a JSON file. The CLI inspects the value: if it resolves to an existing file, the file content is parsed; otherwise the argument itself is parsed as JSON. If neither base nor contrast is provided (and --mcp is not set), help is printed.

Arguments

Argument	Description
[base]	Base JSON string or file path
[contrast]	Contrast JSON string or file path

Options

Option	Alias	Description	Default
--array-compare-method <method>	-a	Array compare method: byIndex, lcs, unordered	byIndex
--key-case-insensitive	-k	Case-insensitive key comparison	false
--value-case-insensitive	-v	Case-insensitive value comparison	false
--numeric-string-equals-number	–	Treat numeric strings as numbers	false
--json-export	-j	Output as JSON format	false
--output <file>	-o	Write output to a file instead of stdout	–
--mcp	–	Run as an MCP server via stdio	false
--version	-V	Print the CLI version	–
--help	-h	Print help	–

Examples

Basic Comparison

compare-json '{"name":"Alice","age":30}' '{"name":"Bob","age":30}'

Output:

┌─────────────┬──────────────┐
│ Key         │ Change Type  │
├─────────────┼──────────────┤
│ (Base) name │ valueChanged │
└─────────────┴──────────────┘

Compare Files

compare-json base.json contrast.json

Array Comparison Methods

# By index (default)
compare-json '[1,2,3]' '[2,3,4]'

# LCS — minimal diff for ordered arrays
compare-json '[1,2,3]' '[2,3,4]' -a lcs
compare-json '[1,2,3]' '[2,3,4]' --array-compare-method lcs

# Unordered — treat as multisets
compare-json '[1,2,3]' '[3,2,1]' -a unordered
compare-json '[1,2,3]' '[3,2,1]' --array-compare-method unordered

Case-Insensitive Comparison

# Case-insensitive keys
compare-json '{"Name":"Alice"}' '{"name":"Alice"}' -k
compare-json '{"Name":"Alice"}' '{"name":"Alice"}' --key-case-insensitive

# Case-insensitive values
compare-json '{"status":"OK"}' '{"status":"ok"}' -v
compare-json '{"status":"OK"}' '{"status":"ok"}' --value-case-insensitive

Numeric String Comparison

compare-json '{"count":1}' '{"count":"1"}' --numeric-string-equals-number

JSON Output

compare-json file1.json file2.json -j
compare-json file1.json file2.json --json-export

Output:

[
  {
    "pathSegments": ["name"],
    "pathString": "name",
    "pathBelongsTo": "both",
    "diffType": "valueChanged"
  }
]

Save to File

# Save table format
compare-json file1.json file2.json -o diff.txt

# Save JSON format
compare-json file1.json file2.json -j -o diff.json

When -o is set, the CLI writes the formatted result to the file and prints Output written to <path> to stdout.

Output Format

Table Format (Default)

A Unicode box-drawn table. Each row is labeled with the side that owns the path:

• (Base) <path> — the path exists on the base side (value or type changes, deletions).
• (Contrast) <path> — the path exists only on the contrast side (additions).
• (Root) — used when the top-level value itself differs.

┌──────────────┬──────────────┐
│ Key          │ Change Type  │
├──────────────┼──────────────┤
│ (Base) a     │ valueChanged │
│ (Base) b     │ deleted      │
│ (Contrast) c │ added        │
└──────────────┴──────────────┘

When the two inputs match exactly, the output is simply:

No differences found

JSON Format

[
  {
    "pathSegments": ["name"],
    "pathString": "name",
    "pathBelongsTo": "both",
    "diffType": "valueChanged"
  },
  {
    "pathSegments": ["age"],
    "pathString": "age",
    "pathBelongsTo": "base",
    "diffType": "deleted"
  },
  {
    "pathSegments": ["email"],
    "pathString": "email",
    "pathBelongsTo": "contrast",
    "diffType": "added"
  }
]

See JSONValueDifference in @compare-json/core for the full shape.

Difference Types

Type	Description
added	Value exists in contrast but not in base.
deleted	Value exists in base but not in contrast.
typeChanged	Value type changed between base and contrast (e.g. number → string).
valueChanged	Value changed while the type stayed the same.

MCP Server

@compare-json/cli also ships an MCP (Model Context Protocol) server that exposes the comparison engine as a tool for AI assistants.

Start the MCP Server

# from a global install
compare-json --mcp

# or via npx
npx @compare-json/cli --mcp

The server communicates over stdio.

Available Tools

compare_json

Compare two JSON values and return their differences.

Input parameters:

Parameter	Type	Required	Description
baseJSON	any	conditional	Base JSON value (already parsed).
baseJSONString	string	conditional	Base JSON as a stringified value (parsed by the server).
baseJSONFilePath	string	conditional	Path to a base JSON file (read and parsed by the server).
contrastJSON	any	conditional	Contrast JSON value (already parsed).
contrastJSONString	string	conditional	Contrast JSON as a stringified value.
contrastJSONFilePath	string	conditional	Path to a contrast JSON file.
options	object	No	Comparison options (see below).

At least one of baseJSON / baseJSONString / baseJSONFilePath must be provided, and at least one of contrastJSON / contrastJSONString / contrastJSONFilePath. When more than one is set for a side, file path takes precedence, then string, then raw value.

Options:

Option	Type	Default	Description
arrayCompareMethod	'byIndex' | 'lcs' | 'unordered'	'byIndex'	Array comparison strategy.
keyCaseInsensitive	boolean	false	Case-insensitive key comparison.
valueCaseInsensitive	boolean	false	Case-insensitive value comparison.
numericStringEqualsNumber	boolean	false	Treat numeric strings as equal to numbers.

Output:

Returns structuredContent.differences — an array of JSONValueDifference objects — and a content[0].text mirror of the same data as JSON text.

{
  "differences": [
    {
      "pathSegments": ["name"],
      "pathString": "name",
      "pathBelongsTo": "both",
      "diffType": "valueChanged"
    }
  ]
}

MCP Client Configuration

Add the following to your MCP client config (e.g. mcp.json):

{
  "mcpServers": {
    "compare-json": {
      "command": "npx",
      "args": ["@compare-json/cli@latest", "--mcp"]
    }
  }
}

License

MIT