PDF Shrink

--- name: PDF Shrink description: Shrink PDF files locally from a single file or folder using npm-only Node.js tooling. Use when the user wants to compress or reduce PDF file size with quality-first presets (minimal or optimal), batch-process a directory, or replace originals in place when the result is smaller. Do not use for text extraction (pdf-context), Markdown conversion (pdf-to-markdown), or image resizing (future image-ops). tags: [documents, pdf, compression, optimize, workflow] audience: [all] status: draft

PDF Shrink

Shrink PDFs locally with quality-first presets. Files never leave the machine — no iLovePDF, no vert.sh, no Ghostscript OS installs.

When to use

• User wants to reduce PDF file size (single file or folder)
• User mentions compress, shrink, optimize, or make PDFs smaller
• Scanned statements, photo-heavy PDFs, or large attachments before archive/email
• Pipeline or batch folder processing on Windows or macOS

When NOT to use

Prerequisites

• Node.js 20.19+
• Install @singleton-sd/ai-plattform-tools-pdf-shrink (once per machine or project)

Install from GitLab npm registry (recommended)

The package is public — no GitLab token required. Point the @singleton-sd scope at the project registry (once per machine or project), in .npmrc:

@singleton-sd:registry=https://gitlab.com/api/v4/projects/singleton-sd%2Fai-plattform%2Ftools%2Fpdf-shrink/packages/npm/

Then install:

npm install @singleton-sd/ai-plattform-tools-pdf-shrink

One-off run (no install; .npmrc scope line still required):

npx @singleton-sd/ai-plattform-tools-pdf-shrink "C:/path/to/document.pdf"

After install, the CLI binary is pdf-shrink (from node_modules/.bin).

Install from source (development)

git clone git@gitlab.com:singleton-sd/ai-plattform/tools/pdf-shrink.git
cd pdf-shrink
yarn install

When working inside the ai-plattform workspace, the tool repo is at tools/pdf-shrink/.

Presets

If savings are under 2% or output would be larger, skip and report already optimal.

Workflow

Task progress:
- [ ] Confirm input path (file or folder)
- [ ] Choose preset (minimal or optimal)
- [ ] Decide output mode (sibling .shrunk.pdf, --output-dir, or --in-place)
- [ ] Run pdf-shrink doctor if first use on this machine
- [ ] Run pdf-shrink on input
- [ ] Report per-file before/after sizes and any skips

Commands

# Check Node + qpdf-compress
pdf-shrink doctor

# Single file — balanced (default)
pdf-shrink "C:/Downloads/large-statement.pdf"

# Near-lossless
pdf-shrink contract.pdf --preset minimal

# Whole folder to separate output directory
pdf-shrink "./scans/" --preset optimal --output-dir "./compressed/"

# Replace original only when smaller
pdf-shrink report.pdf --in-place --preset optimal

# Pipeline-friendly JSON summary
pdf-shrink "./uploads/" --preset optimal --json

Options

Output conventions

• Default output name: {original}.shrunk.pdf beside the source
• --in-place: overwrite original only when strictly smaller
• Never overwrite without --force or --in-place
• Exit codes: 0 success, 1 usage, 2 missing dependency, 3 processing error

Engine

Uses qpdf-compress (Apache-2.0) — QPDF + mozjpeg embedded via npm prebuilds. No Ghostscript or qpdf OS installs.

Why not vert.sh or Ghostscript? VERT.sh has no PDF compress API/CLI today. Ghostscript and qpdf CLI require OS installs — poor fit for cross-platform npm pipelines. For npm-only Node.js compression, qpdf-compress is the preferred engine.