Guides
Read a big file
Read a long document a part at a time. See its structure first, then read only the parts you need, or read it all in pieces of a size you choose.
Step 1 of 3
See the structure
--outline prints only the structure: headings with the paragraphs they run over and tables with their size in a document, slides with their title, shapes, tables, notes and comments in a deck, sheets with their used range, cells and formulas in a workbook, and pages with their form fields, annotations, headings and text in a PDF.
Each part starts with the scope that reads it and ends with its size, so you can pick what to read next.
$ export CV_API_KEY=cv_sk_…Set your key once. lease.docx is the sample.
$ 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 3
Read the parts you need
--scope prints only those parts, comma separated, with the same refs as the whole view.
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.
$ cv read lease.docx --scope p6-p8stdout## [p6] Term5 lines
## [p6] Term [p7] The lease runs for two years from 1 March 2026. [p8] Either party can end it with three months' notice.stderrrev: 3f2a9c1b7d4eStep 3 of 3
Or read it in pieces
--max-chars stops the view at the last whole paragraph, table row, shape, slide or page that fits in that many characters, 500 or more. When it cuts, stderr says where to go on with a next: line.
Read again with that --scope and the same --max-chars until no next: line comes. A single paragraph, row, shape or page larger than the limit is shown whole.
$ cv read lease.docx --max-chars 500stdout# [p1] Lease agreement (Draft)22 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.stderrrev: 3f2a9c1b7d4enext: h1,f1$ cv read lease.docx --scope h1,f1 --max-chars 500stdoutHeader h1 (section 1):7 lines
Header h1 (section 1): [h1/p1] Port of Busan · Pier 3 lease Footer f1 (section 1): [f1/p1] Confidentialstderrrev: 3f2a9c1b7d4eScopes in each format
| Format | Scopes |
|---|---|
| docx | Paragraphs such as p10-p40, a table t1 or its cells t1!A1:C20, a header h1 or a footer f1 |
| pptx | Slides such as s2 or s2-s5, a shape s2/3, or the notes s2/notes |
| xlsx | A sheet Revenue or a range Revenue!A1:D50. A1:D50 alone is the first sheet, and a sheet name that is not one plain word is quoted, as in 'Q1, Q2'!A1:B9 |
Pages such as p3 or p2-p5 |
The same holds for docm and dotx, pptm and potx, and xlsm and xltx.
Any ref an edit takes also works as a scope and shows the part that holds it: s2/3/p1 or s2/4!B2 shows that shape, s2/notes/p1 the notes, and p1/a7 or a form field's name the page it sits on. A scope that names no part of the file fails with invalid_options.
Updated 3 November 2026