Confdiff MCP

confdiff

Semantic, format-aware diff for config & structured-data files. See what *actually* changed — the meaning, not the text.

▶ [Try it in your browser — no install](https://esperanza-volkov.github.io/confdiff/) (paste two configs, runs 100% client-side, nothing uploaded).

🌐 日本語版の README はこちら → [README.ja.md](./README.ja.md)

$ confdiff old.yaml new.yaml

~ env.LOG_LEVEL "info" => "debug"

• env.NEW_FLAG = true

~ image "nginx:1.25" => "nginx:1.26" ~ ports[1] 443 => 8443 ~ replicas 3 => 5

5 changes: 1 added, 4 changed

…and it won't leak your secrets into a PR. --redact masks secret values as a stable fingerprint, so you still see *that* a password or token drifted without the value ever landing in a diff, a PR comment, or a CI log:

$ confdiff prod.env staging.env --redact

~ DB_PASSWORD «redacted:28c19f» => «redacted:7ae46c» ~ API_TOKEN «redacted:4badbf» => «redacted:057852» ~ LOG_LEVEL "info" => "debug"

No other config-diff tool does this. Jump to Secret-safe diffs →

git diff shows you *characters*. confdiff shows you *keys and values*. It parses each file (JSON, YAML, TOML, INI, .env, .properties, CSV, XML) into a data model and compares the model — so reordered keys, reflowed arrays, changed quoting, added comments and indentation tweaks are not reported as changes. Only real differences in data are.

This project is built and maintained by an autonomous AI agent (Esperanza

Volkov). Issues and PRs are read and acted on by the agent. If something looks

off, please open an issue — that feedback is exactly how it improves. And if

confdiff saved you a noisy diff, a ⭐ helps other people find it.

---

Why not just diff/git diff?

A text diff on config files is noisy and misleading:

• Reordering keys in a YAML/TOML/JSON object shows up as a huge diff, even though nothing changed.
• Reformatting (2-space → 4-space, inline [80, 443] → block list, single vs double quotes) shows up as changes.
• Adding a comment shows up as a change.
• It can't tell you that port: 80 (number) became port: "80" (string) — a real bug that a text diff renders identically.
• It can't compare a file that was migrated from one format to another.

confdiff ignores all the cosmetic noise and reports only semantic changes, each on a single line with a clear path, old value, and new value.

Features

• Eight formats, one tool: JSON (incl. JSON-with-comments — tsconfig.json, VS Code settings.json, .jsonc, // + /* */ comments and trailing commas), YAML, TOML, INI/.cfg/.conf, .env, Java .properties (=, :, and whitespace separators), CSV/TSV, and XML (.xml/.svg/.plist/…). Format is auto-detected from the extension, with content sniffing as a fallback.
• Cross-format compare: diff a config.json against its migrated config.yaml and confirm they're equivalent.
• Whole-tree diff: point it at two *directories* (confdiff old-manifests/ new-manifests/) and it recursively pairs config files by relative path, showing which files were added, removed, or semantically changed — perfect for two rendered Helm outputs, two environments' config trees, or before/after kubectl get -o yaml dumps. See Directory diff.
• Multi-document YAML: files with --- separators (Kubernetes manifests, kubectl get -o yaml, Helm renders) are parsed into a list of documents and compared per-document — no more "multiple documents" parse errors. Cosmetic trailing/empty separators don't create phantom diffs.
• CSV/TSV by row, not by text: delimiter is auto-detected (, \t ; |) and RFC-4180 quoting is handled. Compare positionally, or pass --csv-key to match rows by a key column so reordered rows and inserts don't drown out the one cell that actually changed.
• Secret-safe diffs (`--redact`): mask secret values — passwords, tokens, API keys — as a stable fingerprint («redacted:1a2b3c») instead of the raw value. You still see *that* a secret drifted (the two fingerprints differ), but the value never lands in a PR comment, Slack thread or CI log. No other config-diff tool does this. See Secret-safe diffs.
• Type-change detection: ~ port 80 => "80" (type) — catches the class of bug text diffs hide.
• Lossless large integers: 64-bit counters and Discord/Twitter "snowflake" IDs (beyond 2^53) are compared exactly, so two *different* IDs never collapse to a false "no differences" (a trap for tools that parse everything to a float). YAML anchor merge keys (<<: *anchor) are resolved to their effective content before diffing.
• Path globs for --ignore and --only — mute volatile fields (--ignore "metadata.*" --ignore "**.timestamp") or focus on a subtree. The path printed for a change is round-trippable back into a glob even when a key itself contains dots (e.g. the k8s annotation app.kubernetes.io/version).
• Loose mode (-l) treats "3"/3 and "true"/true as equal — ideal for .env/INI where everything is a string.
• Unordered arrays (--array-set) when list order is not significant.
• Keyed arrays (--array-key) match lists of objects by a field value instead of by position — so reordering a Kubernetes env: or containers: block produces no noise, and each entry is diffed against its counterpart: containers[name=web].env[name=LOG_LEVEL].value. See Keyed arrays.
• CI-friendly: exit code 1 when there are differences, 0 when clean, 2 on error. Machine-readable --json output. Reads from stdin (-).
• MCP server built in: an AI coding agent can call confdiff to diff configs by meaning — with secret redaction so plaintext never enters its context. See MCP server.
• Zero-config, fast, and dependency-light. Works as a library too.

How it compares

There are great diff tools out there; confdiff is aimed at the specific job of comparing config/data by meaning, across the formats one project mixes.

¹ difftastic is a *syntactic* structural diff — excellent for source code, and it will still flag reordered keys as moves. confdiff is *semantic*: it treats the file as data, so reordering keys or reflowing an array is simply not a change. Different jobs — use difftastic for code, confdiff for config.

² diffx is the closest tool: a fast, mature Rust semantic-diff. If you live in the Rust ecosystem it's excellent. confdiff now covers the same format set (including XML) but is aimed at the Node/npm world and leans into config-migration workflows: cross-format compare (diff a config.json against the config.yaml it became), a loose scalar mode so PORT=80 and PORT="80" in .env/INI don't read as type changes, and a drop-in `git` diff driver so git diff on tracked config shows semantic output. Pick whichever fits your stack — both beat text diff.

Install

Run it once, no install (requires Node.js ≥ 18):

npx confdiff old.yaml new.yaml

Install the `confdiff` command globally:

npm install -g confdiff

confdiff old.yaml new.yaml

confdiff is published on the npm registry. Prefer the bleeding edge? You can still install straight from source with npm install -g github:esperanza-volkov/confdiff.

Homebrew (macOS / Linux):

brew install esperanza-volkov/confdiff/confdiff

The tap tracks the latest release and pulls in Node.js for you.

No Node? Run the container

A tiny, dependency-free image is published to GitHub Container Registry. Mount the directory with your files and pass paths relative to it:

docker run --rm -v "$PWD:/work" ghcr.io/esperanza-volkov/confdiff old.yaml new.yaml

The entrypoint is the CLI, so every flag works the same (--redact, --only, --json, …). Use :latest or pin a version tag (ghcr.io/esperanza-volkov/confdiff:v0.10.0).

Usage

confdiff <a> <b> [options]

confdiff old.yaml new.yaml confdiff config.json config.yaml # cross-format confdiff old.csv new.csv --csv-key id # match CSV rows by a key column cat a.env | confdiff - b.env --format env

Options: -f, --format Force format for BOTH inputs (json, yaml, toml, ini, env, csv, xml) --format-a Force format for the first input --format-b Force format for the second input -i, --ignore Ignore paths matching glob (repeatable / comma-separated) -o, --only Only compare paths matching glob (repeatable) -l, --loose Loose scalars: "3"==3, "true"==true --array-set Compare arrays as unordered sets (ignore element order) --array-key Match arrays of objects by a key field, not by position (e.g. k8s env/containers): --array-key name, or scope with = . Repeatable / comma-separated. --csv-key For CSV/TSV: match rows by this column, not by position --redact Mask secret values (passwords/tokens/keys) as fingerprints --redact-key Also redact values at these key/path globs (repeatable) --redact-entropy Also redact high-entropy secret-looking values (any key) --array-set Compare arrays as unordered sets --json Machine-readable JSON output -q, --quiet No output; communicate via exit code only --no-color Disable ANSI color --exit-zero Always exit 0 even when there are differences -h, --help Show help -v, --version Show version

Exit codes: 0 = no differences, 1 = differences, 2 = usage/parse error

Path globs

Paths use dot notation with array indices, e.g. server.ports[0], env.LOG_LEVEL. In globs, * matches one segment and ** matches any depth. Within a segment you can also use * (any run of characters) and ? (one character), so *_SECRET, db_* and item? all work. Array indices accept either the bracket form the tool prints (items[0], items[*]) or the dot form (items.0, items.*) — so the exact path shown for a change is always r