Scripting and AI Assistants

Everything Diffoniq shows on screen it can also deliver headless. Two commands cover the two halves of unattended work: /report answers “what is different?” as a file, /sync acts on the answer; a third, /totext, reads one document as text. Both report through an exit code, an output file and a log file — which is exactly what batch files, CI jobs, the Windows Task Scheduler and AI assistants can work with. Started through the console launcher DiffoniqC.exe, they also print their log lines and the shell waits for them like for any console tool.

CommandWhat it doesFull page
/report Compare two files, folders or archives and write the result as HTML, text or JSON. Read-only. Comparison Reports
/sync Synchronize two folders — dry run by default, applied with --execute. Folder Synchronization
/totext Write the text of one Word, Excel, PowerPoint, OpenDocument, EPUB or JSON file — the text a comparison compares. Read-only. below

The compare switches of a normal start work with both — the same engine runs underneath, including the hash cache and rename detection. Spell the command switch as /report or /sync, as shown on their pages.

Reading a document as text: /totext

DiffoniqC /totext <file> [--format text|json] [--out <file>|-]
          [--offset <n>] [--limit <n>] [--sheet <name>] [--slide <n>]
          [--skip-online-only] [--progress]

Diffoniq as a converter alone: one file in, its text out, made by the built-in converters — the same text /report --convert and the MCP tool compare_file compare, from the same cache. Your own converter rules never run here. Without --out the text goes to standard output, so DiffoniqC /totext Angebot.docx > Angebot.txt is all it takes.

The MCP server offers the same as convert_file.

The contract: exit code and JSON

Both commands follow the same scheme — a script can branch on the exit code alone:

ExitMeaning
0No differences
1Differences — report written · sync planned or applied
2Trouble with the outcome — report file not writable · sync finished with errors
3Invalid arguments, or the run failed before doing anything

When something has to act on the differences rather than glance at the count, ask for --format json. The document lists every compared item with a status, both sides with real numbers and ISO timestamps, and a summary block — JSON for scripts describes each key. Two rules matter for any consumer: a side that does not exist is null, and unverified and notCompared are states of their own — never treat them as identical (add --content when the decision must be final).

Connecting an AI assistant (MCP)

AI assistants such as Claude Code, Claude Desktop, Cursor and GitHub Copilot in VS Code can use Diffoniq directly as a tool. They speak the Model Context Protocol (MCP), and DiffoniqC.exe /mcp is a Diffoniq MCP server: the assistant starts it, asks it to compare, and gets the answer as structured data instead of having to read a screen or a file. It offers four tools, all of them read-only — none of them changes a file:

compare_treeCompares two folders or archives — also a folder against a ZIP or 7z, and archives inside archives — and lists what is different, only on one side, or not verified. It first names the folders with the most differences; with path the assistant then looks into one of them. A folder that exists on one side only is one line with the number of files in it. With content it decides by file content and uses the hash cache, so asking again is quick. Files that a cloud service keeps online only are not read and not downloaded: they count as unverified, and the answer says how many. Only with include_online_only are they read — and downloaded. Diffoniq recognizes such a file by the attributes of the Windows cloud files API, which OneDrive, Dropbox and other providers set. Google Drive in streaming mode sets none of them, so a drive labelled Google Drive counts as kept online only as a whole: nothing is read from it, the answer names the drive, and the assistant can ask you. A renamed drive is not recognized; its files are then downloaded when the content is compared. With exclude the assistant leaves out patterns such as backup files, and only with renamed lists the moved and renamed files. The gitignore option applies the .gitignore rules of both trees.
compare_fileCompares two text files and lists the lines that differ, with their line numbers on both sides. Case, spaces and trailing blanks can be ignored. Very long lines are shortened; a binary file shows its size, checksum and the first differing position instead of lines. Word, Excel, PowerPoint (also their old 97-2003 formats), OpenDocument, EPUB and JSON files are compared as text by the built-in converters, so the assistant can tell what changed in a contract or a calculation; the answer names the converter and says whether the files are also identical byte for byte. Its line numbers count the lines of that text, not pages; a spreadsheet line also names its sheet and its row in the sheet, a presentation line its slide and whether it is slide text or notes, a document line its section (body, footnotes, header, footer; an old .doc keeps headers and footers together), and each side lists its sheets with their last row or its number of slides; past 50 sheets, moreSheets says how many are not listed. The converter says where a line lies while it writes the text, so a paragraph that happens to read “Notes:” cannot move it. When only one side can be converted (a password-protected document, a Word 95 file), both are compared byte for byte and the answer says why. With original the bytes are compared instead. ignore_blank_lines passes over lines that are empty or hold only spaces, so that empty paragraphs do not fill the answer. Two Office files whose texts are equal but whose bytes are not — or whose bytes were compared — come with a list of the parts of the package that differ and the document properties (author, dates, program) that changed. Your own converter rules never run here, and folder comparisons stay byte for byte. A file kept online only is refused unless include_online_only is set.
convert_fileReads one Word, Excel, PowerPoint (also the old 97-2003 formats), OpenDocument, EPUB or JSON file as text — exactly the text compare_file compares — so the assistant can read a contract or a calculation without a second file. The answer names the converter, the size and last change of the file and its sheets or slides, and gives every line with its place: sheet and row, slide and slide text or notes, or the section of a document. sheet or slide reads one of them, limit and offset page through a long text. A file that cannot be converted is an error that names the cause, never its bytes. It is /totext underneath. A file kept online only is refused unless include_online_only is set.
sync_previewShows what a synchronization would do — which folders it would create and which files it would copy, rename or (in mirror mode) delete — without doing any of it. It is the dry-run plan of /sync. With content, a file kept online only is skipped instead of downloaded, unless include_online_only is set.

Every answer starts with a summary of the whole comparison and then lists the entries, kept short enough for the assistant to read in one go (about 20,000 characters). When more is there, the answer says how many entries are missing and how to see them: look into a folder, ask only for certain states (for example only what exists on one side), or page on with offset. When all differences lie in one chain of single folders, the overview goes straight down to its end. The tools are also available during the trial period.

Setting it up

Tell the assistant where DiffoniqC.exe is and to start it with /mcp. The examples use the installation folder of the installer; with the portable package, use the folder you extracted.

AssistantConfiguration
Claude Code In a terminal:
claude mcp add diffoniq -- "C:\Program Files\Diffoniq\DiffoniqC.exe" --mcp
Claude Desktop In claude_desktop_config.json (Settings > Developer > Edit Config):
{
  "mcpServers": {
    "diffoniq": {
      "command": "C:\\Program Files\\Diffoniq\\DiffoniqC.exe",
      "args": ["/mcp"]
    }
  }
}
Cursor The same mcpServers block in .cursor\mcp.json of the project, or in %USERPROFILE%\.cursor\mcp.json for all projects.
VS Code (Copilot) In .vscode\mcp.json of the project:
{
  "servers": {
    "diffoniq": {
      "type": "stdio",
      "command": "C:\\Program Files\\Diffoniq\\DiffoniqC.exe",
      "args": ["/mcp"]
    }
  }
}

Then ask in plain words, for example: “Compare D:\releases\v1 with D:\releases\v2 and tell me which files changed” or “What would a mirror of D:\work onto \\nas\backup\work delete?”. Most assistants ask before they use a tool for the first time.

Working with an AI assistant without MCP

An AI coding assistant that can run commands — in a terminal, an IDE or a CI pipeline — can also use the two commands above directly. The reliable pattern is always the same: have the assistant write a JSON report, read the file, then act on it. For example:

Run
  "C:\Program Files\Diffoniq\DiffoniqC.exe" /report "D:\releases\v1" "D:\releases\v2" --out r.json --format json --content -s
then read r.json and summarize what changed. Treat "unverified"
entries as unresolved, not as identical.

The assistant gets the summary counts to decide whether anything happened, the entries to name it, and the exit code to branch on — instead of guessing from screenshots or parsing text layouts. A file comparison works the same way and yields a lines array. The pages linked above spell out every key and exit code; hand them to the assistant when it needs the details.

The console launcher DiffoniqC.exe

Diffoniq.exe is a windowed program, so a shell does not wait for it, does not see its exit code and shows none of its output. Next to it sits DiffoniqC.exe, a small console program for exactly this case: it starts the Diffoniq.exe in its own folder with the same arguments, waits for it, prints the log lines of /report and /sync, and ends with Diffoniq's exit code. Use it wherever a script calls Diffoniq:

"C:\Program Files\Diffoniq\DiffoniqC.exe" /report "D:\Backup" "\\nas\Backup" --out r.json --format json --reverify
echo %errorlevel%
ShellCall
cmd, batch files "C:\Program Files\Diffoniq\DiffoniqC.exe" /report … — then %errorlevel%
PowerShell & "C:\Program Files\Diffoniq\DiffoniqC.exe" /report … — then $LASTEXITCODE
Git Bash / MSYS The shell rewrites /report into a path, so write it as //report: "/c/Program Files/Diffoniq/DiffoniqC.exe" //report … — then $?

Without the launcher

Calling Diffoniq.exe itself still works; the shell just has to be told to wait, or the exit code arrives as 0 before the report exists:

The output file is the safety net: the report and the log are written to a temporary name and renamed on completion — if the file named by --out or --log exists, it is complete. A consumer can never pick up a half-written report, and “wait until the file exists” is a correct pattern when the exit code is out of reach.

ShellRecipe
cmd, batch files start "" /wait "C:\Program Files\Diffoniq\Diffoniq.exe" /report … — then %errorlevel% is real.
PowerShell $p = Start-Process Diffoniq.exe -ArgumentList '/report','…' -Wait -PassThru; $p.ExitCode
Git Bash / MSYS Two traps at once: the shell rewrites /report into a path, and it does not wait. Write the switch as //report and force the wait through a pipe: Diffoniq.exe //report … | cat — the exit code is then ${PIPESTATUS[0]}.

The Task Scheduler and CI runners wait on their own — the nightly sync and nightly report examples show complete schtasks lines.