Guides
Compare two versions
List what differs between two versions of a document, deck, workbook or PDF. Each change is named by its ref, with the text before and after.
Compare two files
cv diff reads the refs view of both files with the same options and prints one line for each ref that differs, starting with changed:, added: or removed:.
Lease agreement (Draft)
Lease agreement (Final)
The tenant pays the rent every month.
The tenant pays the rent every quarter.
edited.docx is the result of Edit a file. The comment it added shows as added, with the ref it has in the edited file.
$ export CV_API_KEY=cv_sk_…Set your key once. lease.docx is the sample.
$ cv diff lease.docx edited.docxstdoutchanged: p1 "Lease agreement (Draft)" -> "Lease agreement (Final)"3 lines
changed: p1 "Lease agreement (Draft)" -> "Lease agreement (Final)"changed: p3 "The tenant pays the rent every month." -> "The tenant pays the rent every quarter."added: c0 "Check this with legal"How parts are matched
Parts are matched by their text first and their ref second. A paragraph, slide or row that was put in or taken out shows alone as added or removed, and the parts after it do not show as changed although their refs moved.
A spreadsheet cell that was empty and got a value is added. A cell with a formula shows the formula too, and long text shows the words around the first difference.
changed: Revenue!F6 12515 -> 12565, formula =SUM(F2:F5) -> =SUM(F2:F4)added: s2/c0.3 "Check the totals"removed: p1/a32 "Check this with finance"Compare part of a file
--scope compares only those parts. Both files must have the same kind of refs view: two documents, two decks, two workbooks or two PDFs.
$ cv diff lease.docx edited.docx --scope p1stdoutchanged: p1 "Lease agreement (Draft)" -> "Lease agreement (Final)"What is not compared
Text without refs, such as the page text of a PDF or the footnotes of a Word document, is not compared part by part. When it differs, a note: line on stderr says so, and text_changed is true in the JSON.
Two identical local files print no differences without a job. cv diff exits 0 when it runs, whatever it finds.
Updated 3 November 2026