Command-line tool (CLI)

The api2convert CLI is the official command-line client for the API. It is a single, self-contained binary — no Node, Python or Java runtime to install — that runs conversions straight from your shell, scripts or CI. It wraps the same job → input → conversion → output lifecycle as the official SDKs, so anything the API can do, the CLI can do too.

• One download, run it — static binaries for Windows, macOS and Linux, no runtime required.
• Guided wizard for interactive use, plus a full flag interface for scripts.
• Automation-ready — batch, recursive, folder watch, --json output and stable exit codes.
• Everything the API does — convert, compress, merge, jobs, async and webhooks.

Install

Pick your platform. Signed, notarized binaries, archives and checksums for every platform are also attached to the latest GitHub release and listed on the Downloads page.

macOS

# Homebrew
brew install qaamgo/tap/api2convert

Linux

# One-liner installer (adds api2convert to your PATH)
curl -fsSL https://raw.githubusercontent.com/QaamGo/api2convert-cli/main/install.sh | sh

# Or a native package from the latest release
sudo dpkg -i api2convert_<version>_linux_amd64.deb   # Debian / Ubuntu
sudo rpm  -i api2convert_<version>_linux_amd64.rpm   # Fedora / RHEL

Windows

Download api2convert_<version>_windows_amd64.zip from the latest release (use the arm64 zip on ARM PCs), unzip it and run api2convert.exe — double-click for the guided wizard, or call it from PowerShell / CMD. Prefer a one-liner that also adds it to your PATH?

# PowerShell
irm https://raw.githubusercontent.com/QaamGo/api2convert-cli/main/install.ps1 | iex

Sign in

Authenticate once with your API key — generate one from your account dashboard (every registered user gets 30 free credits every 24 hours). The key is stored in a 0600 config file; the CLI never prints or logs it. See Authentication for details.

# Save your API key (prompted, masked as you type)
api2convert login

# ...or pass it per-run without storing it
export API2CONVERT_API_KEY=<your-api-key>

Run api2convert with no arguments in a terminal to launch the interactive wizard, which walks you through signing in on first use.

Convert a file

The convert command takes a local file, a URL or stdin, and a target format via --to. Per-format options are passed with repeated --option key=value flags (discover them with api2convert options <target>, below).

# Convert a local document to PDF → report.pdf
api2convert convert report.docx --to pdf

# From a URL or from stdin, into an output directory
api2convert convert https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg --to pdf -o out/
cat scan.tiff | api2convert convert - --to pdf -o scan.pdf

# With per-format options
api2convert convert photo.jpg --to webp --option quality=80

# Force a value to stay a literal string (key:=value skips number/bool coercion)
api2convert convert in.png --to png --option zip_password:=080

Batch & recursive

Convert a whole folder in one call. With --recursive the subfolder structure is preserved under --out-dir.

# Convert every image in ./images to WebP, recursively
api2convert batch ./images --to webp --option quality=80 --out-dir web/ --recursive

Watch a folder

Convert anything dropped into a directory as it arrives — handy for hot folders and integrations.

# Watch ./inbox and convert new files to PDF into ./done
api2convert watch ./inbox --to pdf --out-dir ./done

High-level commands

Convenience verbs wrap common conversions so you don't have to remember the target and options. Each is a thin preset over the convert pipeline.

# Shrink a PDF (same format, smaller file)
api2convert compress big-scan.pdf

# Merge several PDFs into one
api2convert merge a.pdf b.pdf c.pdf --to pdf -o combined.pdf

# Thumbnail and resize
api2convert thumbnail photo.png --option width=320
api2convert resize banner.png --option width=1200

Discover formats & options

The CLI reads the live conversion catalog, so --to, --category and option keys tab-complete and can be searched. You can also browse everything in the Formats Explorer.

# Search the catalog for a target
api2convert formats search word

# List every option a target accepts
api2convert options pdf

Automation & scripting

For pipelines, emit machine-readable JSON and start jobs asynchronously. Combine --json with --quiet so stdout carries only the result (diagnostics and spinners go to stderr).

# Start a job and return immediately (prints a job id)
api2convert convert movie.mov --to mp4 --async

# Wait on a job you started earlier
api2convert jobs wait <job-id>

# Machine-readable output for scripts
api2convert convert report.docx --to pdf --json --quiet

# How many credits you have left
api2convert credits

Exit codes

Every command exits with a stable, documented status — handy for scripting. In --json mode the same value is also in the error envelope as exit_code.

Shell completion

Generate completions for your shell; --to, --category and option keys complete from the live formats catalog.

# bash | zsh | fish | powershell
api2convert completion zsh

Configuration

Settings resolve in the order flag → environment → config file → default:

• API key — --api-key, the API2CONVERT_API_KEY environment variable, or api2convert login.
• Config file — run api2convert config path to print its location (~/.config/api2convert/config.toml on Linux, %AppData%\api2convert on Windows, ~/Library/Application Support on macOS). It is created with 0600 permissions.

Learn more

• Full command reference, examples and changelog: the api2convert-cli README on GitHub.
• Download signed binaries and packages for every platform on the Downloads page.
• New to the API? Start with the Quickstart, or explore every endpoint in the API Reference.
• Prefer to write code? See the SDKs & libraries for PHP, Python, Node.js, Java, .NET, Go, Ruby and Rust.