docs/cli/cv edit

CLI

cv edit

Change parts of a file and keep everything else as it was. The edits are a JSON list, each aimed at a ref or at text it finds.

docxpptxxlsxpdf

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

Usage

cv edit prints a line for each change on stderr, starting with changed:, added: or removed: as cv diff does. Edit a file walks through a whole edit.

Terminal
$ export CV_API_KEY=cv_sk_…

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

Usage
cv edit <file> <output> --edits <edits.json> [--rev <rev>]cv edit <file> --in-place --edits <edits.json> [--rev <rev>]
Terminal
$ cv edit lease.docx edited.docx --edits edits.json --rev 3f2a9c1b7d4e
stderrchanged: 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"

Flags

Flag
--edits <file>The JSON list of edits. - reads it from stdin.
--rev <rev>The revision of the read the refs came from. Edits that aim at a ref need it, and a list that only finds text needs none.
--in-placeWrite the edited file over the input, instead of an output path.
--opt <key=value>track_changes, highlight_edits or author. See Edits people review.
--forceReplace an output file that exists.
--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.

If the file is no longer the one you read, nothing changes and the edit fails with conflict. --in-place writes through a temporary file beside the input that is renamed over it, keeping its permissions. It refuses a file whose name says another format, and leaves the file alone if it changed during the edit.

Edit fields

Field
refThe part to change. With find, the scope it looks in.
findText to find instead of a ref, matched as cv find matches it.
allWith find, change every place it is. A find that matches several places fails without it.
valueThe new text or value. null removes a part that sits in a list and empties one that always has a place.
valuesRows of values for a range of cells, top row first.
formulaA spreadsheet formula, such as =SUM(B2:B5).
insertNew paragraphs after a paragraph, or new rows after a row.
beforeWith insert, put the new parts before it instead.
commentA comment on the part, or a reply to a comment.

All edits apply to the same original, and if any cannot be made none are. cv targets <file> --json shows the edits schema of each target that takes edits.

Spreadsheets

  • Refs are cells or ranges such as Sheet1!B3 or Sheet1!B3:D5, B3 on the first sheet, and whole rows such as Sheet1!5:7.
  • Send numbers as JSON numbers. Text sent to a date cell as YYYY-MM-DD becomes a date.
  • A value on a range goes into every cell of it, and a formula is filled across it with its relative references moving.
  • Whole rows take null to delete them, or insert to add rows after them, or above them with before.
  • Formulas that depend on the edits get new saved results, and --opt highlight_edits=true fills the changed cells.
  • One request takes up to 1,000 edits and 100,000 cells.
edits.json
[  {"ref": "Revenue!B2", "value": 1250},  {"ref": "B9", "formula": "=SUM(B2:B5)"},  {"ref": "Revenue!A7:C8", "values": [["Product E", 410, 430], ["Product F", 120, 95]]}]

Word documents

  • A value is the new text of a paragraph or cell. Send the whole text with your changes: the words you leave keep their formatting, and new words take the formatting of the words they replace.
  • In a paragraph \n is a line break, and in a table cell each line is a paragraph. An automatic number such as 1.2. is not part of the text.
  • insert adds paragraphs after a paragraph, one for each line, and before puts them before it. Paragraphs after an insert or a deletion move, so read the file again before the next edit.
  • A comment becomes a Word comment on a paragraph, a cell, a range of cells or a whole table.
  • Text in content controls, fields, equations, note references and image descriptions cannot change, and headers and footers take values but not comments.
edits.json
[  {"ref": "p3", "value": "The tenant pays the rent every quarter."},  {"ref": "t1!B2:C2", "values": [["1,300", "per quarter"]]},  {"ref": "p5", "comment": "Check this with legal"}]

Presentations

  • Refs are slides such as s1, shapes such as s1/2, paragraphs such as s1/2/p3, table cells such as s1/4!B2, the notes s1/notes and comments such as s1/c0.1.
  • A shape, a table cell or the notes take a value whose lines become paragraphs. Only the words that differ change, so 15% sent over a bold 12% stays bold.
  • null on a slide deletes it with its notes and comments, and the slides after it move up. "" empties a shape.
  • Charts, SmartArt, media and groups themselves cannot change, and tables do not grow.
edits.json
[  {"ref": "s1/2", "value": "Q3 review"},  {"ref": "s2/3/p2", "value": "Volume rose 15%"},  {"ref": "s3/4!B2:C2", "values": [["1,250", "1,310"]]},  {"ref": "s2/notes", "value": "Mention the new berth"},  {"ref": "s2", "comment": "Check the totals"}]

PDF forms

  • A field's ref is its full name, such as Name or applicant.address.city. An annotation is p1/a23, and a page is p1.
  • A field takes text or a number, true or false for a checkbox, or one of its choices. null empties it.
  • A comment adds a note at the top left of a page, beside a field, or as a reply to an annotation.
  • The edits are appended to the file as a new revision, so the rest stays byte for byte. Read-only fields, signature fields and any edit to a signed PDF are refused.
edits.json
[  {"ref": "Name", "value": "Jane Doe"},  {"ref": "Agree", "value": true},  {"ref": "p1/a23", "value": null},  {"ref": "p2", "comment": "Check the totals"}]

With --json

data has changes as the API returns them, output, and rev, the revision of the edited file, which you pass as --rev to edit that file again. It also has job, outputs, format and warnings.

A failed edit gives error.edits: every edit that failed, each with its index, a reason and a message. See When an edit fails.

Terminal
$ cv edit lease.docx edited.docx --edits edits.json --rev 3f2a9c1b7d4e --json
stdout{16 lines
{  "error": {    "code": "invalid_edits",    "edits": [      {        "index": 0,        "message": "edits[0] aims at p9, but the document has 8 paragraphs outside tables",        "reason": "not_found",        "ref": "p9"      }    ],    "message": "edits[0] aims at p9, but the document has 8 paragraphs outside tables",    "retryable": false  },  "ok": false}

Updated 3 November 2026