@compare-xml/cli (JavaScript)

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

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

Installation

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

# yarn
yarn global add @compare-xml/cli

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

Quick Start

# View help
compare-xml --help

# Compare two XML strings
compare-xml '<root><a>1</a></root>' '<root><a>2</a></root>'

# Compare two XML files
compare-xml file1.xml file2.xml

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

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

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

Usage

compare-xml [base] [contrast] [options]

Each positional argument can be either an inline XML string or a path to an XML 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 XML. If neither base nor contrast is provided (and --mcp is not set), help is printed.

Arguments

Argument	Description
`[base]`	Base XML string or file path
`[contrast]`	Contrast XML 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`
`--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-xml '<root><name>Alice</name><age>30</age></root>' '<root><name>Bob</name><age>30</age></root>'

Output:

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

Array Comparison Methods

# By index (default)
compare-xml '<root><items><item>1</item><item>2</item><item>3</item></items></root>' '<root><items><item>2</item><item>3</item><item>4</item></items></root>'

# LCS — minimal diff for ordered arrays
compare-xml '<root><items><item>1</item><item>2</item><item>3</item></items></root>' '<root><items><item>2</item><item>3</item><item>4</item></items></root>' -a lcs

# Unordered — treat as multisets
compare-xml '<root><items><item>1</item><item>2</item><item>3</item></items></root>' '<root><items><item>3</item><item>2</item><item>1</item></items></root>' -a unordered

See Array Comparison Methods for what each strategy does.

Case-Insensitive Comparison

# Case-insensitive keys
compare-xml '<root><Name>Alice</Name></root>' '<root><name>Alice</name></root>' -k

# Case-insensitive values
compare-xml '<root><status>OK</status></root>' '<root><status>ok</status></root>' -v

JSON Output

compare-xml file1.xml file2.xml -j

Output:

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

Save to File

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

# Save JSON format
compare-xml file1.xml file2.xml -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 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) root.a     │ valueChanged │
│ (Base) root.b     │ deleted      │
│ (Contrast) root.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 XMLValueDifference objects — see @compare-xml/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-xml --mcp

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

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

License

MIT