epdf

A simple CLI for selecting, organizing, and preparing PDFs for printing.

Installation

./install.sh

The installer creates an isolated environment in ~/.local/share/epdf and places the command at ~/.local/bin/epdf. When necessary, it adds that directory to PATH automatically. Open a new terminal after installation.

Extract pages

epdf extract book.pdf 1-10,15,r3-r1 -o excerpt.pdf
epdf extract book.pdf 1- --exclude 4,8-10 --odd -o odd-pages.pdf

The syntax accepts individual pages (7), ranges (2-8), descending ranges (8-2), pages counted from the end (r1, r2), open ranges (5-, ..8), and exclusions (!4, --exclude 8-10). --odd and --even filter by the original page number.

Multiple pages per sheet

epdf nup book.pdf 4

Supported values are 2, 3, 4, 6, 8, and 10. Output uses A4 with automatic grid and orientation. Without -o, the example creates book-4up.pdf.

Select pages and optionally add spacing or borders:

epdf nup book.pdf 4 --pages 5-r2 --gap 3 --border

PDF information

epdf info book.pdf

Shows file size, page count, encryption, page dimensions, and orientations.

Merge PDFs

epdf merge cover.pdf book.pdf appendix.pdf -o complete.pdf

Without -o, this creates cover-merged.pdf.

Split into chunks

epdf split book.pdf 20

Creates files such as book-001-020.pdf, book-021-040.pdf, and so on. Use --output-dir DIRECTORY to choose another directory.

Split odd and even pages

epdf parity book.pdf

Creates book-odd.pdf and book-even.pdf. Use --output-dir DIRECTORY to choose another directory.

Rotate pages

epdf rotate scan.pdf 90 --pages 2,4,6

Without --pages, all pages are rotated. The automatic output name is scan-rotated.pdf.

Normalize to A4

epdf normalize scan.pdf

Each page is scaled proportionally onto an A4 sheet while preserving portrait or landscape orientation. This creates scan-a4.pdf.

Mirror pages

epdf mirror scan.pdf horizontal
epdf mirror scan.pdf vertical --pages 2,4-6
epdf mirror scan.pdf both

Without --pages, every page is mirrored. The automatic output name is scan-mirrored.pdf.

Add page numbers

epdf number book.pdf
epdf number book.pdf --start 10 --top

Numbering starts at 1 and appears in the footer by default. This creates book-numbered.pdf.

Add a watermark

epdf watermark book.pdf watermark.pdf

Uses the first page of watermark.pdf as the background of every page and creates book-watermarked.pdf.

Common options

Use -o OUTPUT.pdf when a command supports an explicit output name, and --force to overwrite existing files.

epdf --help
epdf COMMAND --help

Development

Run the test suite from a source checkout:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v

Run the CLI without installing it:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m epdf.cli --help

See AGENTS.md for architecture, invariants, and the handoff guide for future maintainers and coding agents.