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.
| Command | What it does | Full 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.
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.
--format json adds what the plain text cannot say:
file (root, size,
modified in UTC, converted: the converter, and
sheets with their last row or the number of
slides), summary (total lines,
matching the filter, listed,
skipped, omitted) and the lines:
each with line, its place — sheet and
row, slide and part
("slide" or "notes"), or
section ("body", "footnotes",
"endnotes", "header", "footer",
"headersAndFooters" for an old .doc,
"textBoxes") — and text.--sheet or --slide reads one sheet or one
slide; --limit and --offset page through a
long text.not converted: password-protected (encrypted Office
document), a Word 6/95 or Excel 5/95 file, a file no
converter reads, or one too large for the converter (1 GB of
memory, 64 MB of text). A sheet or slide that does not exist is
named the same way. Exit code 0 means the text was written.--skip-online-only refuses a file a cloud service keeps
online only, instead of downloading it.The MCP server offers the same as convert_file.
Both commands follow the same scheme — a script can branch on the exit code alone:
| Exit | Meaning |
|---|---|
0 | No differences |
1 | Differences — report written · sync planned or applied |
2 | Trouble with the outcome — report file not writable · sync finished with errors |
3 | Invalid 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).
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_tree | Compares 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_file | Compares 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_file | Reads 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_preview | Shows 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.
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.
| Assistant | Configuration |
|---|---|
| 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.
C:\… or
\\server\share\…): the server refuses a relative
path, because it would depend on the folder the assistant runs in./mcp, -mcp and --mcp are the
same. Use --mcp in Git Bash, which rewrites a leading
slash into a path.DIFFONIQ_MCP_ONLINE=read in its configuration
entry, for example
"diffoniq": {
"command": "C:\\Program Files\\Diffoniq\\DiffoniqC.exe",
"args": ["/mcp"],
"env": { "DIFFONIQ_MCP_ONLINE": "read" }
}
The assistant is told that the server reads such files; a call that sets
include_online_only to false still leaves them unread.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.
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%
| Shell | Call |
|---|---|
| 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 $? |
PATH; in the portable package it sits beside
Diffoniq.exe in the folder you extracted.> run.txt); they are written as UTF-8.-1073741510, hex C000013A), not
0–3. A /sync --execute stops mid-way: files already copied
stay, a file being copied at that moment can remain incomplete on the
target — run the same sync again and it is copied anew. A
/report writes no partial report.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.
| Shell | Recipe |
|---|---|
| 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.