@stevanfreeborn/png2pdf

Convert PNG images to PDF files from the command line.

Requirements

• Node.js 20 or newer
• npm

Install

Run without installing:

npx @stevanfreeborn/png2pdf .\image.png

Install globally:

npm install --global @stevanfreeborn/png2pdf
png2pdf --help

Local development

cd C:\Users\sfree\Repositories\png2pdf
npm install
npm run build

Run the local development build directly:

npm run dev -- .\image.png

Or link the built CLI so png2pdf is available on your PATH:

npm link
png2pdf --help

Usage

png2pdf <input...> [options]

Inputs can be PNG files, directories, or glob patterns. PNG extensions are matched case-insensitively. Directory inputs are non-recursive unless --recursive is supplied.

Examples

Create a PDF beside each PNG:

png2pdf .\screenshots\login.png
png2pdf .\screenshots

Write batch output to a directory:

png2pdf ".\screenshots\**\*.png" --recursive --out-dir .\pdfs

Combine images into one multi-page PDF:

png2pdf ".\screenshots\*.png" --merge --output .\album.pdf

Fit images onto A4 pages with a margin:

png2pdf .\diagram.png --page-size a4 --margin 18

Options

Option	Description
-d, --out-dir <dir>	Write batch PDFs to this directory.
-m, --merge	Combine all PNGs into one multi-page PDF.
-o, --output <file>	Output path for merged mode. Requires --merge.
-r, --recursive	Recurse into directory inputs.
--page-size <size>	fit, a4, or letter. Defaults to fit.
--margin <points>	Page margin in PDF points. Defaults to 0.
--dpi <number>	DPI used to size fit pages. Defaults to 96.
-f, --force	Overwrite existing output files.
-q, --quiet	Suppress success and progress output.
-V, --version	Print the version.
-h, --help	Print help.

Behavior

• By default, every PNG becomes its own PDF beside the source file.
• With --merge, all PNGs become pages in one PDF, in sorted path order.
• fit pages use the image's physical dimensions at the selected DPI plus margins.
• a4 and letter pages fit and center the image while preserving its aspect ratio. Page orientation follows the image orientation.
• Transparent PNGs keep their alpha channel.
• Existing files are not overwritten unless --force is used.
• In batch mode, failures are reported without stopping other conversions. The command exits with code 1 if any conversion fails.
• Batch output collisions, such as two inputs with the same basename and one output directory, are rejected before conversion starts.

Development

npm run typecheck
npm run lint
npm test
npm run build
npm run format:check