pdfcli

A dead-simple PDF toolkit for the command line — merge, insert, rotate, remove, extract, split, compress, and inspect. Built as a friendlier alternative to qpdf for everyday PDF wrangling: every command comes with real usage examples baked into its own --help, and page selection uses one consistent, human-readable syntax everywhere.

Features

• merge — combine PDFs (and images!) into one file, in order
• add — insert pages from another PDF or image at any position
• rotate — rotate specific pages, or the whole document
• remove — drop pages you don't want
• extract — pull out just the pages you do want
• split — break a PDF into one-file-per-page or fixed-size chunks
• compress — shrink file size by downsampling oversized images
• info — page count, metadata, page sizes, rotation, at a glance

Images (.png, .jpg, .jpeg, .bmp, .tif, .tiff, .gif, .webp) are accepted anywhere a PDF is, and are converted to a page on the fly — so pdfcli merge combined.pdf cover.pdf photo.jpg report.pdf just works.

Install

git clone <this-repo-url>
cd pdfcli
pip install -r requirements.txt --break-system-packages   # or use a venv

Make it a real command on your PATH:

chmod +x pdfcli.py
sudo ln -s "$(pwd)/pdfcli.py" /usr/local/bin/pdfcli

Then just run pdfcli from anywhere.

Usage

Run pdfcli --help for the full command list, or pdfcli COMMAND --help for that command's own examples. Quick tour:

# Combine PDFs (and images!) into one, in order
pdfcli merge combined.pdf cover.pdf report.pdf appendix.png

# Drop pages from another PDF/image into an existing one
pdfcli add report.pdf signature.png -o signed.pdf --at end
pdfcli add report.pdf extra.pdf -o updated.pdf --at 3 --pages 1-2

# Rotate specific pages (or all of them)
pdfcli rotate scan.pdf 90 -o fixed.pdf --pages 2,4,6

# Remove pages
pdfcli remove report.pdf 2,4,7-9 -o trimmed.pdf

# Pull out just the pages you want
pdfcli extract book.pdf 1,3,5-9 -o excerpt.pdf

# Split into one-file-per-page (or N-page chunks)
pdfcli split book.pdf --outdir pages/
pdfcli split book.pdf --outdir chapters/ --every 10

# Shrink a PDF full of scanned pages or big photos
pdfcli compress scan.pdf -o scan_small.pdf --level high

# Metadata, page count, page sizes, rotation
pdfcli info report.pdf

Page specs

Anywhere you pass a list of pages (--pages, remove, extract), the syntax is:

Syntax	Meaning
3	a single page
1,3,5	a list
5-9	an inclusive range
end/last	the final page (works in ranges too: 5-end)
-1	negative indexing from the end (-2 = second-to-last)

All page numbers are 1-based, the way a human counts them.

Compression levels

compress downsamples embedded images above a size threshold and recompresses page content streams. It leaves already-small images alone, so it's safe to run on anything — worst case, nothing changes.

Level	Max image dimension
low	2000 px
medium	1400 px (default)
high	1000 px

Gains are biggest on scanned documents or PDFs stuffed with high-res photos. A text-heavy PDF won't shrink much — there's not much fat to trim.

Requirements

• Python 3.9+
• Typer — CLI framework
• pypdf — PDF manipulation
• Pillow — image handling
• rich — terminal output

License

MIT — do whatever you want with it.