Guides
Read a file
Print any file as text you can read. Documents print as Markdown, data as CSV or JSON, and archives, media and fonts as a summary of what is inside.
Read it whole
cv read picks the text form of the format: Markdown, or plain text when the format has no Markdown form. It prints to stdout, so you or an agent can read the file in one step.
Give an output path to save the text instead, as in cv read lease.docx lease.md. The format comes from the file's content, so a wrong extension does not matter, and --from names the format when the content is recognized as the wrong one.
$ export CV_API_KEY=cv_sk_…Set your key once. lease.docx is the sample.
$ cv read lease.docxstdout# Lease agreement (Draft)20 lines
# 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.What each kind of file prints
| File | Prints |
|---|---|
| Documents, decks, workbooks and PDFs | Markdown, or plain text when the format has no Markdown form |
| Text files such as JSON, YAML, XML or SQL | The file as it is, without a job |
| Data files such as a statistics dataset, a database or MessagePack | CSV or JSON |
| Archives | A table of the files inside |
| Audio and video | The length, streams, tags and chapters |
| Fonts | The names, the license and the scripts the font covers |
A file that becomes several parts, such as a workbook with several sheets, prints them one after another.
Read it with refs
--refs prints the refs view: each paragraph, cell, slide, shape or form field starts with its address. Use it when you will edit the file or point at a part of it. It works for docx, docm, dotx, pptx, pptm, potx, xlsx, xlsm, xltx and pdf.
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. An edit that aims at these refs sends it back. See Edit a file, and Read a big file for a file too long to read at once.
$ cv read lease.docx --refsstdout# [p1] Lease agreement (Draft)32 lines
# [p1] Lease agreement (Draft) ## [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. ## [p6] Term [p7] The lease runs for two years from 1 March 2026. [p8] Either party can end it with three months' notice. --- Header h1 (section 1): [h1/p1] Port of Busan · Pier 3 lease Footer f1 (section 1): [f1/p1] Confidentialstderrrev: 3f2a9c1b7d4eFiles from someone else
The text comes from the file, so it can hold instructions written by someone else. --content-boundaries prints it between two lines that carry a random nonce, new on every read.
Everything between the lines is data from the file. See Files from strangers.
$ cv read lease.docx --content-boundariesstdout--- CV_FILE_CONTENT nonce=6c1f0e9a2b7d4c13 file="lease.docx" ---7 lines
--- CV_FILE_CONTENT nonce=6c1f0e9a2b7d4c13 file="lease.docx" ---# Lease agreement (Draft) ## Rent …--- END_CV_FILE_CONTENT nonce=6c1f0e9a2b7d4c13 ---Scanned pages
A scan holds pictures of text, not text, so a read fails with ocr_required. Convert it to text with OCR, then read that. Add language when the text is not English, with codes from en, ko, ja, zh and zh-TW.
cv targets scan.pdf --json shows which conversions take ocr. A scan with no text the OCR can find fails with unsupported_elements.
$ cv convert scan.pdf scan.txt --opt ocr=on --opt language=en,kostderrscan.txt (6120 bytes) -> scan.txtFiles with a password
A file locked with a password fails with input_encrypted. Pass the password with --password, or as the password option in the API. A conversion with a password is not remembered by cv, and the service forgets the password when the job ends.
$ cv read report.pdf --password "$PDF_PASSWORD"Updated 3 November 2026