Use Diff Anything from the CLI, Git, and CI

Find the installed executable

The desktop binary uses --cli for command-line operation so an ordinary launch remains graphical. A Microsoft Store installation declares the diff-anything.exe execution alias; Windows users can run it when that alias is enabled in App execution aliases.

The Mac App Store version runs in Apple's App Sandbox, so its own executable cannot read files named on a command line: run from Terminal, it says to install the command-line helper and exits with 2. Install the free Diff Anything command-line helper, a signed and notarized installer from this site, not from the Mac App Store, for Apple silicon and Intel Macs with macOS 13 or later. It installs diff-anything in /usr/local/bin, so every command, Git setting, and batch manifest in this guide works unchanged. The helper does not need --cli but accepts it.

The helper has Pro when Pro was bought or restored in the Diff Anything app on the same Mac, under the same macOS user; open the app once after buying or restoring. Without Pro, it works as the free CLI, with 10 comparisons a day counted on their own. It never uses the network.

• Windows: diff-anything.exe --cli left.json right.json
• Mac, with the helper installed: diff-anything --cli left.json right.json
• Check the installed version: diff-anything --cli --version
• Mac: which -a diff-anything shows which diff-anything runs first, and diff-anything --pro-status says whether Pro was found

Download the command-line helper for Mac →

Enter explicit CLI mode

Provide two source paths and optionally choose --mode auto|text|json|yaml|toml|ini|plist|xml|csv|env|http|api|notebook|sqlite|folder|archive|document|binary, --format summary|terminal|json, and --exit-code. Saved desktop profiles are not CLI options.

An interactive terminal defaults to the highlighted terminal view; redirected output defaults to the concise summary. Use --color auto|always|never, --language for an explicit highlighting language, and --context to control unchanged lines around terminal hunks.

CLI document mode compares extracted content; the rendered-page PDF Visual diff is a desktop feature. For automated layout checks, render corresponding PDF pages to equal-size images, compare each pair with Pro binary mode, and read its image metrics from JSON.

Text comparisons take the app's ignore options: --ignore-text and --ignore-lines with a regular expression, --ignore-preset for built-in timestamp and ID patterns, --ignore-comments, and --ignore-columns, such as 1-6 or 73-.

Free CLI use is limited to text, JSON, and notebooks, files up to 5 MiB per side, and 10 new comparison sessions per local calendar day. Specialist modes, reports, applying patches, and all batch manifests require Pro.

• Terminal: diff-anything --cli --format terminal --color auto left.ts right.ts
• JSON: diff-anything --cli --format json --mode json left.json right.json
• Rendered page image: diff-anything --cli --mode binary --format json reference.png candidate.png
• Use absolute or workflow-stable paths in automation.

Interpret exit codes

For a single comparison, add --exit-code when automation needs differences to affect the process result. Without it, a valid single comparison returns zero even when changes are found.

For an API schema check, use --mode api --fail-on breaking instead: identical or equivalent schemas pass, non-breaking changes are allowed, and the process returns 1 only for breaking changes or changes the rules could not classify.

Batch mode returns zero when every case passes its failOn check, one when a case fails it or could not be compared, and two when the batch cannot be invoked or its manifest cannot be read or parsed.

• Single with --exit-code: 0 clean, 1 differences, 2 invalid invocation, unreadable input, or comparison failure.
• Single with --mode api --fail-on breaking: 1 only for breaking or unclassified API changes.
• Batch: 0 every case passes, 1 a case fails its failOn check or could not be compared, 2 manifest or invocation failure.

Choose output for the consumer

The terminal format gives a person a Unicode-safe, syntax-highlighted diff with line numbers and compact hunks. The concise summary suits ordinary logs, while JSON preserves structured results for another tool.

Batch workflows accept YAML or JSON manifests and can emit summary, JSON, JUnit, or SARIF. JUnit fits test-report surfaces; SARIF fits code-scanning and static-analysis surfaces that understand the standard. Keep diagnostic messages separate from machine-readable output so parsers receive valid documents.

Configure Git difftool

Register Diff Anything as a Git diff tool and pass Git's LOCAL and REMOTE paths into explicit CLI mode. Do not add --exit-code to the difftool command: Git expects the tool to process a changed pair successfully.

Git creates temporary files for some comparisons, so review or edit through the workflow supported by the selected mode rather than assuming a temporary source should be retained.

• git config --global diff.tool diff-anything
• git config --global difftool.diff-anything.cmd 'diff-anything.exe --cli "$LOCAL" "$REMOTE"'

Use Diff Anything for git diff

To have git diff itself use Diff Anything, define it as a diff driver and assign it to file types in the repository's .gitattributes file. Git runs the driver only for the files assigned to it, names them by their repository paths, and shows mode changes and renames the way its own diff does.

git diff uses the driver for the assigned files; git log -p and git show use it with --ext-diff. Leave --exit-code out of a diff driver, because Git stops at the first changed file when a driver exits with a non-zero status. On the free plan, a file the plan does not cover is listed as not compared and git diff continues with the rest.

• git config --global diff.diff-anything.command 'diff-anything --cli --format terminal --color auto'
• .gitattributes: *.json diff=diff-anything
• .gitattributes: *.yaml diff=diff-anything
• diff-anything --cli --integration-help prints this configuration

Merge with Git

With Pro, Diff Anything is both a merge driver and a merge tool. The merge driver merges the files you assign to it in .gitattributes whenever Git merges: a JSON, YAML, TOML, or INI file is merged by its data, conflict markers surround only the values both sides changed differently, and the driver returns 1 while conflicts remain. --name %P gives it the file's own name, which decides its format.

The merge tool is the app itself. git mergetool starts it for each conflicted file and waits: the window shows the base, local, and remote versions and the result, with the conflicts Git left as structured conflicts. Save & Close writes the merged file and exits with 0; Cancel or closing the window exits with 1 and leaves the file as Git wrote it. On Windows, the Microsoft Store version is the merge tool. On a Mac, the same settings run the command-line helper, which reads the files, opens the merge in a window of the Mac App Store app, starting the app when it is not running, and writes the merged file when you choose Save & Close; without the helper, open the conflicted file in the app and choose Resolve.

• git config --global merge.diff-anything.driver 'diff-anything --cli --merge %O %A %B --output %A --name %P'
• git config --global merge.tool diff-anything
• git config --global mergetool.diff-anything.cmd 'diff-anything --merge-tool "$BASE" "$LOCAL" "$REMOTE" "$MERGED"'
• git config --global mergetool.diff-anything.trustExitCode true
• .gitattributes: *.toml merge=diff-anything

Run batch manifests

A Pro batch manifest can be a YAML or JSON object with a comparisons array, or a top-level array of comparisons. Each item supports name, left, right, an optional mode, failOn (any or breaking), and warningsAsDifferences; desktop profile rules are not batch-manifest fields, and a misspelt key is reported as an error.

Use --format junit or --format sarif for established review surfaces, or --format json for the detailed result. Write the report with --output FILE, which writes UTF-8; in Windows PowerShell 5.1, redirecting with > writes UTF-16, which many CI tools reject. For API cases with failOn: breaking, JUnit lists the breaking changes with their rule codes and SARIF reports each finding under its rule code.

• Manifest item: { "name": "API schema", "left": "baseline/openapi.json", "right": "build/openapi.json", "mode": "api", "failOn": "breaking" }
• JUnit file: diff-anything --cli --batch comparisons.json --format junit --output report.xml
• SARIF file: diff-anything --cli --batch comparisons.json --format sarif --output report.sarif

Debug automation failures

Reproduce the exact paths, mode, format, and exit-code option locally. Check whether the process can read both sources and whether the shell can create any redirected output file.

CLI comparisons use their built-in default options; they do not load desktop profiles. When results differ by machine, inspect source bytes, line endings, paths, and app version before changing expectations.