CLI
JSON and exit codes
With --json, every command prints one JSON object on stdout. The exit code says what kind of failure it was, with or without --json.
The envelope
A command that succeeds prints ok as true and its result in data. Any failure prints ok as false and the error, with the same exit code as without --json. Parse that instead of the human output.
$ export CV_API_KEY=cv_sk_…Set your key once. Every cv command reads it.
$ cv find lease.docx Draft --jsonstdout{17 lines
{ "data": { "find": "Draft", "format": "docx", "found": [ { "count": 1, "ref": "p1", "text": "Lease agreement (Draft)" } ], "rev": "3f2a9c1b7d4e", "total": 1, "warnings": [] }, "ok": true}$ cv convert lease.docx --to mp3 --jsonstdout{16 lines
{ "error": { "code": "unsupported_conversion", "message": "there is no conversion from docx to mp3", "param": "to", "retryable": false, "suggestions": [ "pdf", "docx", "odt", "rtf", "docm" ] }, "ok": false}What data holds
| Command | data |
|---|---|
| targets | The target list, with the input format in from. See cv targets. |
| convert | The job object as the server sent it. See Jobs. |
| read | text, or output with an output path, rev, and next_scope when --max-chars cut the view. |
| find | total, and found, a list of {ref, count, text}. |
| edit | changes as the API returns them, output, and rev, the revision of the edited file. |
| diff | changes, a list of {ref, was, change, before, after}, a and b with each file's rev, and text_changed. |
read, find, edit and diff also have format and warnings. The keys come in alphabetical order.
Errors
Without --json, a failure prints one line on stderr, error: <code>: <message>, and when there are suggestions a second line, try: <targets or command>. A suggested command keeps your options.
With --json the error has code, message and retryable, and param, suggestions and edits when they apply. Error codes lists every code and what to do next.
$ cv convert lease.docx --to mp3stderrexit 2error: unsupported_conversion: there is no conversion from docx to mp3try: pdf, docx, odt, rtf, docmExit codes
| Code | Meaning and what to do |
|---|---|
| 0 | Success. Continue. |
| 1 | An input problem: the file is corrupt, encrypted, unreadable, missing or expired. Read stderr, and add --password when the code is input_encrypted. |
| 2 | The request cannot run as asked: an unsupported target, an invalid option or edit, or several files where one was asked. Run the try: line, or pick one of its targets. Do not retry the same command. |
| 3 | Authentication. CV_API_KEY is missing or invalid. |
| 4 | Temporary: the network, a busy service or a server error. Retry once after a short wait, then report. |
| 5 | An account limit: balance, storage, file size or files per job. Tell the user. --pages can bring the files per job under the limit. |
find and diff exit 0 when they run, whatever they find. A code this cv does not know yet prints as error: unknown: <code>: <message> and exits 4 when the server marks it retryable, 2 otherwise.
Updated 3 November 2026