CLI
cv convert
Convert one or more files to another format. The output's extension names the format, or --to does.
Usage
An input is a local path, a file id such as file_01J…, or - for stdin. The input format comes from the file's content, so a wrong extension does not matter.
$ export CV_API_KEY=cv_sk_…Set your key once. Every cv command reads it.
cv convert <input>... [<output>] [--to <format>]$ cv convert report.docx --to mdcv convert report.docx report.pdfcv convert slides.pdf pages/ --to png --pages 1-3cv convert a.pdf b.pdf merged.pdfcv convert scan1.png scan2.jpg scans.pdfcurl -sL https://example.com/a.pdf | cv convert - --to txtcv convert photo.png web.webp --opt quality=80Where the result goes
With two or more paths the last one is the output and the rest are inputs, as with cp. When the output's extension and --to disagree, cv stops instead of writing one format under the other's name.
- With no output path, or
-as the output, the result goes to stdout. - An output file that already exists is replaced only with
--force. - A conversion that makes many files, such as one picture per page, needs a directory as the output. An output file or stdout asks for exactly one file, so
cvfails and itstry:line shows the directory form.
$ cv convert slides.pdf pages/ --to png --pages 1-3stderr3 files -> pages/Join or convert one by one
Several inputs with one output file are joined into one file: each input is converted to the format the join takes, then joined in the order given. Several inputs with a directory as the output are converted one by one.
Options go to the join when files are joined, and to each conversion otherwise. A target listed with inputs: many in cv targets --json is a join.
$ cv convert a.pdf b.pdf merged.pdfstderrmerged.pdf (412870 bytes) -> merged.pdfFlags
| Flag | |
|---|---|
| --to <format> | The format to make, when the output has no extension or there is no output path. |
| --pages <range> | Pages to read, such as 1-3,7. |
| --dpi <n> | Raster resolution in dots per inch, 36 to 600. |
| --opt <key=value> | Any other option of the conversion. Repeat it for several. |
| --refs | Draw the refs on pictures of a PDF or deck, or write the JSON refs view with --to json. |
| --force | Replace 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. |
| --json | Print 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. |
Options
Options that have no flag of their own go through --opt key=value. Text options keep the value as text, so --opt encrypt_password=1234 stays a string, and other values are read as JSON when they can be.
Each conversion takes only some options. One it does not take fails with invalid_options, and the message names the options it does take. cv targets <file> --json lists them with their ranges and defaults, and Options lists them all.
$ cv convert report.pdf small.pdf --opt compression=ebook --opt grayscale=truestderrsmall.pdf (1180342 bytes) -> small.pdfWaiting and running it again
Large inputs take time, and the upload is usually longer than the conversion. When --wait runs out, the job keeps running. Running the same command again waits for that job instead of starting and paying for a new one.
The same local file is not uploaded twice, and the same conversion is not run twice: cv remembers both in ~/.cache/cv. See Files from strangers.
With --json
data is the job object as the server sent it. The result is saved only when you name an output path. Without one nothing is downloaded, and each entry of outputs has a url you can fetch.
$ cv convert report.docx --to pdf --jsonstdout{27 lines
{ "data": { "id": "job_01JC9W…", "inputs": [ … ], "object": "job", "outputs": [ { "name": "report.pdf", "object": "file", "url": "https://…", … } ], "status": "done", "to": "pdf", "transforms": [ { "id": "docx>pdf", "version": "75f37498" } ], … }, "ok": true}Updated 3 November 2026