Concepts
Refs and revisions
A ref is the address of one part of a file. A revision names the file and the way its refs were read. Together they let an edit change the part you read and nothing else.
The refs view
A read with refs prints a file as text with a ref in front of every part an edit can aim at: a paragraph, a table and its cells, a slide and its shapes, a sheet's cells, a form field.
The view shows text the way an edit's find matches it, so what you read is what you aim at. Comments and tracked changes show as > lines after their part.
In the API the view is a job's refs. {"refs": {}} asks for the whole view. Ask for it as json to get its units, each with its ref and its text.
$ export CV_API_KEY=cv_sk_…Set your key once. lease.docx is the sample.
$ cv read lease.docx --scope p2-p5stdout## [p2] Rent14 lines
## [p2] Rent [p3] The tenant pays the rent every month. [p4] Rent is paid to the port office by the fifth day. [t1]| | A | B | C ||---|---|---|---|| 1 | Due | Amount | Paid to || 2 | Rent | 1,300 | Port office || 3 | Deposit | 2,600 | Port office | [p5] Late payments carry a fee of 2% a month.stderrrev: 3f2a9c1b7d4eWhat a ref names
A ref is a position in the file as convert.dev reads it, not an id stored in the file. Read the same file again and you get the same refs.
| Format | Refs |
|---|---|
| Word | Paragraphs p3, and h1/p1 and f1/p2 in headers and footers. Tables t1, cells t1!B2, ranges t1!B2:C4, rows t1!3:3. Comments c1. |
| Spreadsheets | Cells Sheet1!B3, ranges Sheet1!B3:D5, rows Sheet1!5:5. B3 alone is on the first sheet. |
| Presentations | Slides s1, shapes s1/2, their paragraphs s1/2/p3, table cells s1/4!B2, notes s1/notes. |
| PDF forms | Fields by name, such as Name. Pages p1 and annotations p1/a2. |
Every ref also works as a scope. --scope p2-p5 reads those parts, and a single ref shows the part that holds it. See Read a big file.
What a revision is
Every read with refs gives the file's revision, rev, such as 3f2a9c1b7d4e. cv prints it on stderr. In the API it is on each of the job's inputs.
A revision is a hash of two things: the file's bytes, and the way convert.dev reads refs from that format. It changes when either one changes, and the same file uploaded again, even after the first upload was deleted, gets the same revision.
So the same file can get a new revision after convert.dev changes how it reads that format. Refs from the old read may then point at other parts, and the revision is what tells the two reads apart.
Why an edit needs one
A ref is only an address. p5 in one file is another paragraph in another file, or in the same file after a paragraph was added above it.
So an edit that names a ref sends the revision of the read the ref came from. convert.dev checks it against the file before it changes anything. If they differ, nothing changes and the edit fails with conflict. Read the file again and take the refs from that read.
A revision covers the whole file, not one read. Every ref in one list of edits must come from the read whose revision you send.
An edit that only finds text, with no ref, needs no revision. The text says where it goes.
When refs move
An edit that adds or removes parts moves the refs after them. Put a paragraph after p3, and the old p4 becomes p5.
Its output comes with no revision, because a ref from the first read would hit another part of it. cv edit says the refs after it moved, and with --json its rev is null.
- To edit again, add the next edits to the same list and send it to the original file with its revision.
--jsongives that command intry. - Or read the edited file and take every ref from that new read.
Do not mix the two. A ref you saw in the edited file points at another part of the original. An edit that changes text and adds or removes nothing keeps every ref in place, and its output has a revision for the next edit.
Use them
- Edit a file goes through a read, an edit and a check, step by step.
- Read a big file reads a long file one scope at a time.
- See where the refs are draws the refs on the pages of a PDF or the slides of a deck.
Updated 3 November 2026