Converter Agent CLI

Advanced, fast, and ergonomic CLI for file conversions using ConvertAPI. Convert MS Office, images, and PDFs; batch process directories; merge, split, compress, and watermark PDFs; and perform image joins and format conversions.

Screenshots

CLI Agent Converter

DOCX to PNG

HEIC to PNG

PDF Before Compression (60MB original size)

PDF After Compression Applied (13MB compressed size)

Requirements

• Python 3.9+
• ConvertAPI secret key

Setup

1. Create and activate a virtual environment

python3 -m venv .venv && source .venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

3. Configure your API key (env var or .env)

export CONVERT_API_SECRET="<your-secret>"
# or create a .env file in the project root with the same variable

Usage

Run the CLI via the entrypoint:

python main.py --help

Set defaults globally with environment variables or per-command flags. All commands support --out-dir and most support --concurrency.

Generic conversions

# Convert a DOCX to PDF
python main.py convert to pdf ./docs/report.docx --out-dir out

# Batch convert recursively to PNG
python main.py convert to png ./images --recursive --out-dir out

# Convert by specifying from-format explicitly (optional)
python main.py convert to pdf ./path/to/file.pptx --from-format pptx --out-dir out

PDF operations

# Merge PDFs (output is a directory)
python main.py pdf merge ./a.pdf ./b.pdf -o out

# Compress PDFs (batch)
python main.py pdf compress ./pdfs --recursive --out-dir out

# Split by custom ranges
python main.py pdf split ./big.pdf --custom-range "1,3,4-5,6-9" --out-dir out

# Overlay watermark
python main.py pdf watermark-overlay ./input.pdf --overlay ./watermark.pdf --out-dir out

Image operations

# Join images
python main.py image join ./img1.png ./img2.png --out-dir out

# Compress images (JPEG only)
python main.py image compress ./imgs --recursive --out-dir out

# Convert formats
python main.py image convert ./imgs --to webp --recursive --out-dir out

Configuration

Environment variables:

• CONVERT_API_SECRET: ConvertAPI secret key (required)
• CONVERT_API_CONCURRENCY: Default concurrency for batch operations (default: 4)
• CONVERT_API_TIMEOUT: HTTP timeout seconds (default: 120)
• CONVERT_API_BASE_URL: Custom base URL (optional)

Notes

• Local file paths and URLs are supported where applicable
• Output files are saved into the specified output directory
• Image compression currently supports JPEG (.jpg/.jpeg) only