Guides
Edit a file
Change cells of a spreadsheet, paragraphs of a Word document, text on a slide or fields of a PDF form. Everything you do not touch stays as it was.
Before you start
You can edit Word documents, decks, workbooks and PDF forms: docx, docm, dotx, pptx, pptm, potx, xlsx, xlsm, xltx and pdf.
Everything you can change has a ref, an address such as p3, t1!B2, s2/3, Revenue!B2 or a form field's name. A ref stays the same each time the same file is read.
The examples edit lease.docx, a short lease with a rent table. The steps are the same for every format.
$ export CV_API_KEY=cv_sk_…Set your key once. lease.docx is the sample.
Step 1 of 5
See the structure
--outline prints only the structure. Each part starts with the scope that reads it and ends with its size.
$ cv read lease.docx --outlinestdout8 paragraphs, 1 table, 1 header, 1 footer; 573 characters in the refs view8 lines
8 paragraphs, 1 table, 1 header, 1 footer; 573 characters in the refs view - p1-p8: Lease agreement (Draft) (8 paragraphs, 1 table, 460 characters) - p2-p5: Rent (4 paragraphs, 1 table, 303 characters) - t1: table of 3 rows and 3 columns (142 characters) - p6-p8: Term (3 paragraphs, 123 characters)- h1: header for section 1 (1 paragraph, 36 characters)- f1: footer for section 1 (1 paragraph, 20 characters)stderrrev: 3f2a9c1b7d4eStep 2 of 5
Read what you will change
--scope prints only those parts, with the same refs as the whole view. Each paragraph starts with its ref, and each table is a grid, so a cell is t1!B2.
Lease agreement (Draft)
Rent
The tenant pays the rent every month.
Rent is paid to the port office by the fifth day.
| DueA1 | AmountB1 | Paid toC1 |
| RentA2 | 1,300B2 | Port officeC2 |
| DepositA3 | 2,600B3 | Port officeC3 |
Late payments carry a fee of 2% a month.
Term
The lease runs for two years from 1 March 2026.
Either party can end it with three months' notice.
The rev on stderr is the file's revision. Keep it for step 4.
--content-boundaries.$ 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: 3f2a9c1b7d4eStep 3 of 5
Write the edits
edits.json holds a JSON list. Aim each edit at a ref, or at text it finds.
Check a find before you send it. cv find prints each ref that holds the text, and stderr says whether an edit finds it once, nowhere, or in several places.
Lease agreement (Draft)
Rent
The tenant pays the rent every month.
Rent is paid to the port office by the fifth day.
| Due | Amount | Paid to |
| Rent | 1,300 | Port office |
| Deposit | 2,600 | Port office |
Late payments carry a fee of 2% a month.
Term
The lease runs for two years from 1 March 2026.
Either party can end it with three months' notice.
[ {"ref": "p3", "value": "The tenant pays the rent every quarter."}, {"find": "Draft", "value": "Final"}, {"ref": "p5", "comment": "Check this with legal"}]$ cv find lease.docx Draftstdoutp1: "Lease agreement (Draft)"stderrfinds "Draft" once, in p1Step 4 of 5
Send them with the revision
Pass the revision you read. If the file is no longer the one you read, or convert.dev now gives its refs another way, nothing changes and the edit fails with conflict.
Lease agreement (Final)
Rent
The tenant pays the rent every quarter.
Rent is paid to the port office by the fifth day.
| Due | Amount | Paid to |
| Rent | 1,300 | Port office |
| Deposit | 2,600 | Port office |
Late payments carry a fee of 2% a month.
convert.devCheck this with legalTerm
The lease runs for two years from 1 March 2026.
Either party can end it with three months' notice.
--in-place instead of an output path writes the edited file over the input. In the API, the edited file in outputs has its own rev for the next edit.
$ cv edit lease.docx edited.docx --edits edits.json --rev 3f2a9c1b7d4estderrchanged: edits[0] p3 "The tenant pays the rent every month." -> "The tenant pays the rent every quarter."3 lines
changed: edits[0] p3 "The tenant pays the rent every month." -> "The tenant pays the rent every quarter."changed: edits[1] p1 "Lease agreement (Draft)" -> "Lease agreement (Final)"added: edits[2] c0 "Check this with legal"Step 5 of 5
Check what changed
cv diff lists every ref whose text differs between the two files. To undo one edit, send the list again without it, to the original file.
Each change names the part by its ref in the edited file, so the refs go on with the edited file's rev. A part that moved also has was, the ref it had in the file you sent, and an edit that changed nothing is left out.
Lease agreement (Draft)
Lease agreement (Final)
The tenant pays the rent every month.
The tenant pays the rent every quarter.
$ 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"When an edit fails
All edits apply to the same original. If any cannot be made, none are. Say the header also held the word Draft. The find now matches two places, so the edit fails and the file stays as it was.
Lease agreement (Draft)
Rent
The tenant pays the rent every month.
Rent is paid to the port office by the fifth day.
| Due | Amount | Paid to |
| Rent | 1,300 | Port office |
| Deposit | 2,600 | Port office |
Late payments carry a fee of 2% a month.
Term
The lease runs for two years from 1 March 2026.
Either party can end it with three months' notice.
With --json, error.edits lists every edit that failed, each with its index, ref, a reason and a message. Fix or drop those edits and send the list again.
| reason | What it means |
|---|---|
| invalid | The edit is malformed. Fix it. |
| not_found | The ref is not in the file, such as a ref past the end of the document, or the find matches no place. |
| ambiguous | The find matches several places. Add a ref, or set all to true. |
| overlap | Two edits change the same place. Join them or drop one. |
| merged | The cell is part of a merged cell. Aim at the top-left cell the message names. |
| tracked_changes | The paragraph has tracked changes. Send a comment instead. |
| locked | A protected sheet or cell, a read-only field or a signed PDF. A person must unlock the file first. |
| unsupported | This edit cannot be made here. The message says why, and what to change first when something can. |
$ cv edit lease.docx edited.docx --edits edits.json --rev 3f2a9c1b7d4estderrexit 2error: invalid_edits: edits[1] finds "Draft" 2 times, in p1, h1/p1; add a ref to aim at one of them, or set all to true to change every oneEdits people review
--opt track_changes=true writes the text changes of a Word document as tracked changes by convert.dev, which a person accepts or rejects in Word. On a spreadsheet, --opt highlight_edits=true fills the changed cells.
--opt author=Legal names who made the tracked changes and comments, in Word, PowerPoint and PDF. Without it they are by convert.dev, and PDF comments carry no author.
Lease agreement (DraftFinal)
Rent
The tenant pays the rent every monthquarter.
Rent is paid to the port office by the fifth day.
| Due | Amount | Paid to |
| Rent | 1,300 | Port office |
| Deposit | 2,600 | Port office |
Late payments carry a fee of 2% a month.
convert.devCheck this with legalTerm
The lease runs for two years from 1 March 2026.
Either party can end it with three months' notice.
$ cv edit lease.docx edited.docx --edits edits.json --rev 3f2a9c1b7d4e --opt track_changes=trueUpdated 3 November 2026