docs/cli/cv read

CLI

cv read

Print a file as text you can read. cv read picks Markdown, plain text, CSV, JSON or a summary to suit the format.

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

Usage

The text goes to stdout, or to the output path when you give one. See Read a file for what each kind of file prints.

Terminal
$ export CV_API_KEY=cv_sk_…

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

Usage
cv read <file> [<output>] [--refs] [--outline] [--scope <refs>] [--max-chars <n>] [--content-boundaries]
Terminal
$ cv read lease.docx --scope p2-p5
stdout## [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: 3f2a9c1b7d4e

Flags

Flag
--refsPrint the refs view, with the address of every part, and the file's rev: on stderr.
--outlinePrint only the structure, each part with the scope that reads it and its size.
--scope <refs>Print only these parts, comma separated, with the same refs as the whole view.
--max-chars <n>Stop at the last whole part that fits in n characters, 500 or more, and print next: on stderr.
--content-boundariesPrint the text between two lines that carry a random nonce. Only when printing, not with an output path.
--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.

--outline, --scope and --max-chars turn --refs on. They work for docx, docm, dotx, pptx, pptm, potx, xlsx, xlsm, xltx and pdf. See Read a big file.

What stderr says

A read with refs prints rev: <rev>, the file's revision, on stderr, outside the text. When --max-chars cut the view, a next: line gives the scope to read next. Warnings start with warning: and errors with error:.

Terminal
$ cv read lease.docx --max-chars 500 > part1.md
stderrrev: 3f2a9c1b7d4enext: h1,f1

With --json

data has text, what it would print, or output with an output path. It also has rev, next_scope, the scope to read next when --max-chars cut the view, to, the format it printed, job, format and warnings.

A plain text file prints without a job, so job and rev are null.

Updated 3 November 2026