ConvertAPI CLI Client

Convert your files with our command-line file conversion utility

ConvertAPI helps in converting various file formats. Creating PDF and Images from various sources like Word, Excel, Powerpoint, images, web pages or raw HTML codes. Merge, Encrypt, Split, Repair and Decrypt PDF files and many other file manipulations. You can integrate it into your application in just a few minutes and use it easily.

The ConvertAPI CLI makes it easier to use the Convert API from your shell without having to build your own HTTP calls. You can get your free secret at https://www.convertapi.com/a

Installation

Download compressed CLI executable

Linux: convertapi_lin.tar.gz
Linux ARM64: convertapi_lin_arm.tar.gz
Darwin (MacOS): convertapi_mac.tar.gz
Darwin (MacOS) M1: convertapi_mac_arm.tar.gz
Windows: convertapi_win.zip

(this utility can also be built from source code for many other CPU and OS)

Unzip executable

unzip convertapi_*.zip

And you are done. Optionally you can move the executable file to a more appropriate place and make utility accessible for all local users. On Linux it would be:

sudo mv convertapi /usr/local/bin

Usage

Before you start

In order to use this CLI utility, you must create your free trial account on https://www.convertapi.com site.
After the sign-up process, you will get your secret at https://www.convertapi.com/a . The secret will be used in every CLI utility run.

Basic file conversion

Before we go into detail, a short usage example of how to convert DOCX file to PDF.

convertapi --iformat=docx --oformat=pdf --params="file:@/path/to/test.docx" --out="@/path/to/resultdir" --secret=your-api-secret

Arguments documentation

--iformat

Input file format (file name extension). All supported input formats can be found here. Example:

--iformat=docx

--oformat

Output file format (file name extension). All supported output formats can be found here. Example:

--oformat=pdf

--params

Conversion parameter list. All supported conversion parameters can be found here. Parameter name and value is separated by : colon. Parameters are separated by , comma. Example:

--params="param1:value1, param2:value2, param3:value3"

Comma , inside the parameter value must be escaped with \,.

File parameter

Special case is file parameter. Value can have a prefix and can be provided as an array with the ; semicolon separator. The prefix can be one of those:

no prefix

No prefix means that the value is http or https scheme URL to a file. Example:

--params="file:https://cdn.convertapi.com/cara/testfiles/presentation.pptx"

@

Parameter values starting with @ are treated as paths to the local files or directories. Example:

--params="file:@/path/to/myfile.doc"

<

Parameters with < values are substituted with the data taken from STDIN. As a raw value can only be the URL then, in this case, the data received from STDIN should be URL or URL array separated by \n Example:

--params="file:<"

@<

Parameters with @< values are substituted with the data taken from STDIN. Data received from STDIN should be a local path to the file or directory. It can also be an array of paths separated by \n. Example:

--params="file:@<"

<<

Parameters with << values are substituted with the data taken from STDIN. Data received from STDIN should be file content. Example:

--params="file:<<"

Array parameter

If a parameter name is suffixed with [], the parameter is treated as an array parameter. Mainly array parameters are used when one conversion needs to accept multiple files (e.g. pdf merge or zip compression).

--params="files[]:@/path/to/dir"

--out

The argument defines how conversion result should be outputted. Values can be one of those:

url

This is the default output method. It prints to STDOUT URL or array of URLs that point to the converted files. This method should be used for conversion chaining.

@

Value prefixed with @ is treated as a local file or directory path where the converted file will be stored. Example:

--out="@/path/to/result.pdf"

--out="@/path/to/resultdir"

stdout

The Conversion result will be outputted to STDOUT. If the result contains multiple files, second and the following files will be outputted to the file descriptors starting from 3.

--out="stdout"

--secret

ConvertAPI user secret. Get your secret at https://www.convertapi.com/a

--token

Token can be used instead of --secret parameter. Tokens can be generated in your dashboard. --apikey parameter must be set if token authentication is used.

--apikey

ApiKey can be retrieved from your dashboard. --apikey parameter must be set if token authentication is used.

--version

Outputs CLI utility version information and exits.

--help

Displays a short usage information.

Examples

Convert a local DOCX file to PDF A3 page size saving the result to /path/to/resultdir

convertapi --iformat=docx --oformat=pdf --params="file:@/path/to/test.docx, pagesize:a3" --out="@/path/to/resultdir" --secret=your-api-secret

Merge all PDF files that are located in /path/to/dir directory and save it locally

convertapi --iformat=pdf --oformat=merge --params="files[]:@/path/to/dir" --out="@/path/to/resultdir" --secret=your-api-secret

Convert remote PPTX file to PDF saving the result to /path/to/result.pdf

convertapi --iformat=pptx --oformat=pdf --params="file:https://example.com/myfile.pptx" --out="@/path/to/result.pdf" --secret=your-api-secret

Convert from DOCX to JPG and ZIP the result JPG files into a single archive

convertapi --iformat=docx --oformat=jpg --params="file:@/path/to/test.docx" --secret=your-api-secret \
    | convertapi --iformat=jpg --oformat=zip --params="files[]:<" --out="@/path/to/result.zip" --secret=your-api-secret

Convert DOCX to PDF and save the result on a remote server over SSH

convertapi --iformat=docx --oformat=pdf --params="file:@/path/to/test.docx" --out=stdout --secret=your-api-secret \
    | ssh user@myserver "cat >/tmp/my.pdf"

Get the PDF file from a remote server, convert it to JPG and save the result locally

ssh user@server "cat /tmp/my.pdf" \
    | convertapi --iformat=pdf --oformat=jpg --params="file:<<" --out=@/path/to/resultdir --secret=your-api-secret

Do PDF->JPG and DOCX->JPG conversions in parallel and ZIP the converted JPG files

( \
    convertapi --iformat=pdf --oformat=jpg --params="file:/path/to/dir" --secret=your-api-secret \
    & convertapi --iformat=docx --oformat=jpg --params="file:@/path/to/dir" --secret=your-api-secret \
) | convertapi --iformat=jpg --oformat=zip --params="files[]:<" --out=@/path/to/resultdir  --secret=your-api-secret

Merge PDFs files from various locations: a remote SSH server, local file, local directory, and a remote HTTP server. Save the result file on a remote SSH server. All of this is done without writing to disk.

ssh user@server1 "cat /tmp/my.pdf" \
    | convertapi --iformat=pdf --oformat=merge --params="files[]:<<;@/path/to/test.pdf;@/path/to/dir;https://example.com/my.pdf" --out=stdout --secret=your-api-secret \
    | ssh user@myserver2 "cat >/tmp/my.pdf"

Issues & Comments

Please leave all comments, bugs, requests, and issues on the Issues page. We'll respond to your request ASAP!

License

The ConvertAPI CLI is licensed under the MIT license. Refer to the LICENSE file for more information.