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"
or
--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.