docs/cli/cv diff

CLI

cv diff

List what differs between two versions of a file, one line for each ref.

lease.docx8 paragraphs · 1 table · 1 header · 1 footer
Sample

Usage

Both files must have the same kind of refs view: two documents, two decks, two workbooks or two PDFs. Each line starts with changed:, added: or removed:.

See Compare two versions for how parts are matched.

Terminal
$ export CV_API_KEY=cv_sk_…

Set your key once. lease.docx is the sample.

Usage
cv diff <a> <b> [--scope <refs>]
Terminal
$ cv diff lease.docx edited.docx
stdoutchanged: 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"

Flags

Flag
--scope <refs>Compare only these parts, comma separated.
--from <format>The format of a local file or stdin, instead of detecting it from the content. File ids that are already uploaded keep the format they have.
--password <value>The password of an encrypted input.
--wait <seconds>How long to wait for the job, 300 by default. When the wait runs out the job keeps running, and the same command again waits for it.
--jsonPrint one JSON object on stdout instead. See JSON and exit codes.
--api <url>The server, from CV_API_URL, or https://api.convert.dev.
--key <key>The API key, from CV_API_KEY.

What it prints

  • A part that moved names the ref it had, as in changed: p12 (was p11), followed by the text before and after.
  • A cell with a formula adds it, as in changed: Revenue!F6 12515 -> 12565, formula =SUM(F2:F5) -> =SUM(F2:F4).
  • Long text shows the words around the first difference.
  • When text without refs differs, such as the page text of a PDF, a note: line on stderr says so.
  • Two identical local files print no differences without a job.

cv diff exits 0 when it runs, whatever it finds.

With --json

data.changes is a list of {ref, was, change, before, after}, the same records an edit reports. was is the ref in the first file when it differs, and a cell with a formula adds formula. a and b give each file with its rev, and text_changed is true when text without refs differs.

Terminal
$ cv diff lease.docx edited.docx --json
stdout{25 lines
{  "data": {    "a": {      "file": "lease.docx",      "rev": "3f2a9c1b7d4e"    },    "b": {      "file": "edited.docx",      "rev": "9b04e1c27a5f"    },    "changes": [      {        "after": "Lease agreement (Final)",        "before": "Lease agreement (Draft)",        "change": "changed",        "ref": "p1"      },      …    ],    "format": "docx",    "text_changed": false,    "warnings": []  },  "ok": true}

Updated 3 November 2026