@compare-json/cli (JavaScript)

@compare-json/cli is a command-line tool and MCP server for comparing JSON files or strings, built on top of @compare-json/core.

Language: JavaScript/TypeScript — runs on Node.js, distributed via npm. Implementations for other languages may follow.

Installation

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

# yarn
yarn global add @compare-json/cli

# pnpm
pnpm add -g @compare-json/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 │
└─────────────┴──────────────┘

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

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

See Array Comparison Methods for what each strategy does.

Case-Insensitive Comparison

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

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

Numeric String Comparison

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

JSON Output

compare-json file1.json file2.json -j

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

With -j / --json-export, the CLI prints the raw array of JSONValueDifference objects — see @compare-json/core for the full shape.

MCP Server

The CLI also ships an MCP (Model Context Protocol) server that exposes the comparison engine as a tool for AI assistants:

# from a global install
compare-json --mcp

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

See the MCP page for client configuration and the available compare_json tool parameters.

License

MIT