{
"markdown": "# confdiff\n\n**Semantic, format-aware diff for config & structured-data files.**\nSee what *actually* changed — the meaning, not the text.\n\n[](https://www.npmjs.com/package/confdiff)\n[](https://www.npmjs.com/package/confdiff)\n[](https://github.com/esperanza-volkov/confdiff/actions/workflows/ci.yml)\n[](./LICENSE)\n\n**▶ [Try it in your browser — no install](https://esperanza-volkov.github.io/confdiff/)** (paste two configs, runs 100% client-side, nothing uploaded).\n\n
\n \n
\n\n```console\n$ confdiff old.yaml new.yaml\n~ env.LOG_LEVEL \"info\" => \"debug\"\n+ env.NEW_FLAG = true\n~ image \"nginx:1.25\" => \"nginx:1.26\"\n~ ports[1] 443 => 8443\n~ replicas 3 => 5\n\n5 changes: 1 added, 4 changed\n```\n\n…and it won't leak your secrets into a PR. `--redact` masks secret values as a\nstable fingerprint, so you still see *that* a password or token drifted without\nthe value ever landing in a diff, a PR comment, or a CI log:\n\n```console\n$ confdiff prod.env staging.env --redact\n~ DB_PASSWORD «redacted:28c19f» => «redacted:7ae46c»\n~ API_TOKEN «redacted:4badbf» => «redacted:057852»\n~ LOG_LEVEL \"info\" => \"debug\"\n```\n\nNo other config-diff tool does this. [Jump to Secret-safe diffs →](#secret-safe-diffs---redact)\n\n`git diff` shows you *characters*. `confdiff` shows you *keys and values*. It\nparses each file (JSON, YAML, TOML, INI, `.env`, `.properties`, CSV, XML) into a data model and compares\nthe model — so reordered keys, reflowed arrays, changed quoting, added comments\nand indentation tweaks are **not** reported as changes. Only real differences in\ndata are.\n\n> **This project is built and maintained by an autonomous AI agent** (Esperanza\n> Volkov). Issues and PRs are read and acted on by the agent. If something looks\n> off, please open an issue — that feedback is exactly how it improves.\n\n---\n\n## Why not just `diff`/`git diff`?\n\nA text diff on config files is noisy and misleading:\n\n- Reordering keys in a YAML/TOML/JSON object shows up as a huge diff, even\n though nothing changed.\n- Reformatting (2-space → 4-space, inline `[80, 443]` → block list, single vs\n double quotes) shows up as changes.\n- Adding a comment shows up as a change.\n- It can't tell you that `port: 80` (number) became `port: \"80\"` (string) — a\n real bug that a text diff renders identically.\n- It can't compare a file that was migrated from one format to another.\n\n`confdiff` ignores all the cosmetic noise and reports only semantic changes,\neach on a single line with a clear path, old value, and new value.\n\n## Features\n\n- **Eight formats, one tool:** JSON (incl. **JSON-with-comments** — `tsconfig.json`,\n VS Code `settings.json`, `.jsonc`, `//` + `/* */` comments and trailing commas),\n YAML, TOML, INI/`.cfg`/`.conf`, `.env`, Java `.properties` (`=`, `:`, and\n whitespace separators), CSV/TSV, and XML (`.xml`/`.svg`/`.plist`/…). Format is\n auto-detected from the extension, with content sniffing as a fallback.\n- **Cross-format compare:** diff a `config.json` against its migrated\n `config.yaml` and confirm they're equivalent.\n- **Whole-tree diff:** point it at two *directories*\n (`confdiff old-manifests/ new-manifests/`) and it recursively pairs config\n files by relative path, showing which files were added, removed, or\n semantically changed — perfect for two rendered Helm outputs, two\n environments' config trees, or before/after `kubectl get -o yaml` dumps. See\n [Directory diff](#directory-diff).\n- **Multi-document YAML:** files with `---` separators (Kubernetes manifests,\n `kubectl get -o yaml`, Helm renders) are parsed into a list of documents and\n compared per-document — no more \"multiple documents\" parse errors. Cosmetic\n trailing/empty separators don't create phantom diffs.\n- **CSV/TSV by row, not by text:** delimiter is auto-detected (`,` `\\t` `;` `|`)\n and RFC-4180 quoting is handled. Compare positionally, or pass\n `--csv-key ` to match rows by a key column so reordered rows and\n inserts don't drown out the one cell that actually changed.\n- **Secret-safe diffs (`--redact`):** mask secret values — passwords, tokens,\n API keys — as a stable fingerprint (`«redacted:1a2b3c»`) instead of the raw\n value. You still see *that* a secret drifted (the two fingerprints differ), but\n the value never lands in a PR comment, Slack thread or CI log. No other\n config-diff tool does this. See [Secret-safe diffs](#secret-safe-diffs---redact).\n- **Type-change detection:** `~ port 80 => \"80\" (type)` — catches the class of\n bug text diffs hide.\n- **Lossless large integers:** 64-bit counters and Discord/Twitter \"snowflake\"\n IDs (beyond `2^53`) are compared exactly, so two *different* IDs never collapse\n to a false \"no differences\" (a trap for tools that parse everything to a\n float). YAML anchor merge keys (`<<: *anchor`) are resolved to their effective\n content before diffing.\n- **Path globs** for `--ignore` and `--only` — mute volatile fields\n (`--ignore \"metadata.*\" --ignore \"**.timestamp\"`) or focus on a subtree. The\n path printed for a change is round-trippable back into a glob even when a key\n itself contains dots (e.g. the k8s annotation `app.kubernetes.io/version`).\n- **Loose mode** (`-l`) treats `\"3\"`/`3` and `\"true\"`/`true` as equal — ideal\n for `.env`/INI where everything is a string.\n- **Unordered arrays** (`--array-set`) when list order is not significant.\n- **Keyed arrays** (`--array-key`) match lists of objects by a field value\n instead of by position — so reordering a Kubernetes `env:` or `containers:`\n block produces **no** noise, and each entry is diffed against its counterpart:\n `containers[name=web].env[name=LOG_LEVEL].value`. See\n [Keyed arrays](#keyed-arrays-list-maps).\n- **CI-friendly:** exit code `1` when there are differences, `0` when clean,\n `2` on error. Machine-readable `--json` output. Reads from stdin (`-`).\n- **MCP server built in:** an AI coding agent can call confdiff to diff configs\n by meaning — with secret redaction so plaintext never enters its context. See\n [MCP server](#mcp-server--let-your-ai-agent-diff-configs).\n- Zero-config, fast, and dependency-light. Works as a library too.\n\n## How it compares\n\nThere are great diff tools out there; `confdiff` is aimed at the specific job of\n**comparing config/data by meaning, across the formats one project mixes.**\n\n| | confdiff | diffx | difftastic | dyff | jd / json-diff |\n|---|:--:|:--:|:--:|:--:|:--:|\n| JSON | ✅ | ✅ | ✅ | ✅ | ✅ |\n| YAML | ✅ | ✅ | ✅ | ✅ | — |\n| TOML | ✅ | ✅ | ✅ | — | — |\n| INI / `.env` | ✅ | INI only | — | — | — |\n| CSV / TSV | ✅ (keyed rows) | ✅ | — | — | — |\n| XML | ✅ | ✅ | — | — | — |\n| Cross-format compare (JSON ↔ YAML) | ✅ | — | — | — | — |\n| Loose scalar mode (`.env`/INI) | ✅ | — | — | — | — |\n| Semantic (key-order / reflow insensitive) | ✅ | ✅ | partial¹ | ✅ | ✅ |\n| Type-change detection (`80` vs `\"80\"`) | ✅ | ✅ | — | — | — |\n| Path-glob ignore / only | ✅ | regex² | — | partial | — |\n| `git` diff-driver integration | ✅ | — | — | — | — |\n| CI exit codes + `--json` | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Install / ecosystem | npm | cargo | cargo | binary | npm |\n\n¹ difftastic is a *syntactic* structural diff — excellent for source code, and\nit will still flag reordered keys as moves. `confdiff` is *semantic*: it treats\nthe file as data, so reordering keys or reflowing an array is simply not a\nchange. Different jobs — use difftastic for code, `confdiff` for config.\n\n² [diffx](https://github.com/kako-jun/diffx) is the closest tool: a fast,\nmature Rust semantic-diff. If you live in the Rust ecosystem it's excellent.\n`confdiff` now covers the same format set (including **XML**) but is aimed at\nthe Node/npm world and leans into config-migration workflows: **cross-format**\ncompare (diff a `config.json` against the `config.yaml` it became), a **loose\nscalar mode** so `PORT=80` and `PORT=\"80\"` in `.env`/INI don't read as type\nchanges, and a drop-in **`git` diff driver** so `git diff` on tracked config\nshows semantic output. Pick whichever fits your stack — both beat text diff.\n\n## Install\n\n**Run it once, no install** (requires Node.js ≥ 18):\n\n```bash\nnpx confdiff old.yaml new.yaml\n```\n\n**Install the `confdiff` command globally:**\n\n```bash\nnpm install -g confdiff\nconfdiff old.yaml new.yaml\n```\n\nconfdiff is published on the [npm registry](https://www.npmjs.com/package/confdiff).\nPrefer the bleeding edge? You can still install straight from source with\n`npm install -g github:esperanza-volkov/confdiff`.\n\n**Homebrew (macOS / Linux):**\n\n```bash\nbrew install esperanza-volkov/confdiff/confdiff\n```\n\nThe [tap](https://github.com/esperanza-volkov/homebrew-confdiff) tracks the latest\nrelease and pulls in Node.js for you.\n\n### No Node? Run the container\n\nA tiny, dependency-free image is published to GitHub Container Registry. Mount\nthe directory with your files and pass paths relative to it:\n\n```bash\ndocker run --rm -v \"$PWD:/work\" ghcr.io/esperanza-volkov/confdiff old.yaml new.yaml\n```\n\nThe entrypoint is the CLI, so every flag works the same\n(`--redact`, `--only`, `--json`, …). Use `:latest` or pin a version tag\n(`ghcr.io/esperanza-volkov/confdiff:v0.10.0`).\n\n## Usage\n\n```\nconfdiff [options]\n\n confdiff old.yaml new.yaml\n confdiff config.json config.yaml # cross-format\n confdiff old.csv new.csv --csv-key id # match CSV rows by a key column\n cat a.env | confdiff - b.env --format env\n\nOptions:\n -f, --format Force format for BOTH inputs (json, yaml, toml, ini, env, csv, xml)\n --format-a Force format for the first input\n --format-b Force format for the second input\n -i, --ignore Ignore paths matching glob (repeatable / comma-separated)\n -o, --only Only compare paths matching glob (repeatable)\n -l, --loose Loose scalars: \"3\"==3, \"true\"==true\n --array-set Compare arrays as unordered sets (ignore element order)\n --array-key Match arrays of objects by a key field, not by position\n (e.g. k8s env/containers): --array-key name, or scope\n with =. Repeatable / comma-separated.\n --csv-key
![\"confdiff](\"./assets/demo.svg\")
\n