@compare-xml/cli (JavaScript)

Compare XML files or strings in a terminal, or expose comparison through MCP.

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

Language: JavaScript/TypeScript — runs on Node.js and is distributed via npm.

Installation

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

# yarn
yarn global add @compare-xml/cli

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

You can also run commands without a global install by replacing compare-xml with npx @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 JSON
compare-xml file1.xml file2.xml --json-export

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

# Start the MCP server over stdio
compare-xml --mcp

Usage

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

Each positional argument can be inline XML or a file path. If the argument resolves to an existing file, the CLI reads that file; otherwise it parses the argument itself as XML. If neither input is provided and --mcp is not set, the CLI prints help.

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`	Repeated-element method: `byIndex`, `lcs`, `unordered`	`byIndex`
`--key-case-insensitive`	`-k`	Case-insensitive element and attribute names	`false`
`--value-case-insensitive`	`-v`	Case-insensitive text and attribute values	`false`
`--json-export`	`-j`	Output differences as JSON	`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 │
└──────────────────┴──────────────┘

Repeated-Element 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 — align ordered collections with insertions and deletions
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 — compare multisets, retaining duplicate occurrence counts
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 XML Comparison Rules for guidance on choosing a strategy.

Case-Insensitive Comparison

# Element and attribute names
compare-xml '<root><Name>Alice</Name></root>' '<root><name>Alice</name></root>' -k

# Text and attribute values
compare-xml '<root><status>OK</status></root>' '<root><status>ok</status></root>' -v

JSON Output

compare-xml file1.xml file2.xml -j

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

Save to File

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

# Save JSON output
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)

The default Unicode table labels each row with the side that owns the path:

(Base) <path> — the path exists on the Base side, including value changes and deletions.
(Contrast) <path> — the path exists only on the Contrast side.
(Root) — the top-level value itself differs.

When the inputs match under the selected options, the output is:

No differences found

JSON Format

With -j / --json-export, the CLI prints the raw array of XMLValueDifference objects. See @compare-xml/core for the complete shape.

MCP Server

The CLI also exposes the comparison engine to AI assistants through MCP:

# From a global install
compare-xml --mcp

# Or through npx
npx @compare-xml/cli --mcp

See the XML MCP guide for client configuration and compare_xml parameters.

License

MIT