PDF Toolkit

Extract data from PDFs (text, tables, images, OCR), create new PDFs, and manipulate existing ones (merge, split). All operations use bundled Bun TypeScript scripts that produce structured JSON output.

When to use

• When extracting text, tables, or images from PDF files
• When OCR-ing scanned PDFs or image-based PDFs
• When creating new PDFs from text, markdown, or images
• When merging multiple PDFs into one
• When splitting a PDF into separate files (by page, range, or chunk)
• When the user mentions "PDF", "document extraction", or "scanned document"

Do NOT use when:

• Working with Word (.docx), Excel (.xlsx), or other non-PDF formats
• The user needs interactive PDF form filling (not supported)
• The user needs PDF encryption or digital signatures

Prerequisites

All scripts require Bun. Dependencies are auto-installed on first run.

Workflow

1. Identify the operation

Determine which script to use based on what the user needs:

scripts/extract-text.ts

scripts/extract-tables.ts

scripts/extract-images.ts

scripts/ocr-pdf.ts

scripts/create-pdf.ts

scripts/merge-pdf.ts

scripts/split-pdf.ts

How to choose between extract-text and ocr-pdf: If the PDF contains selectable text (you can copy-paste from it), use

extract-text.ts

ocr-pdf.ts

extract-text.ts

ocr-pdf.ts

2. Run the script

All scripts follow the same conventions:

bun run scripts/<script>.ts [options] <input-file>

• JSON output goes to stdout (parseable by agents)
• Progress and diagnostics go to stderr
• Exit code 0 = success, 1 = error
• All scripts support

  --help

  for full usage

3. Process the output

Parse the JSON output for downstream use. All scripts return structured JSON with consistent patterns (file metadata, page-level results, summary counts).

Script Reference

extract-text.ts — Text extraction

# All text from a PDF
bun run scripts/extract-text.ts document.pdf

# Specific pages as JSON
bun run scripts/extract-text.ts --pages 1,3,5-7 --format json report.pdf

# Per-page text to a file
bun run scripts/extract-text.ts --per-page --output out.txt slides.pdf

--pages

1,3,5-7

--format

text

json

--per-page

--output

Uses

unpdf

ocr-pdf.ts

extract-tables.ts — Table extraction

# Extract all tables as JSON
bun run scripts/extract-tables.ts report.pdf

# Extract tables from specific pages as CSV
bun run scripts/extract-tables.ts --pages 2,3 --format csv data.pdf

--pages

--format

json

csv

tsv

--output

Detects tables by delimiter patterns: tab-separated, pipe-separated (

|

extract-images.ts — Image extraction

# Extract all images as PNG
bun run scripts/extract-images.ts document.pdf

# Extract from pages 1-3 as JPEG, min 100px
bun run scripts/extract-images.ts --pages 1-3 --format jpeg --min-size 100 brochure.pdf

# List images without saving
bun run scripts/extract-images.ts --list-only slides.pdf

--pages

--output-dir

--format

png

jpeg

--min-size

--list-only

Uses

mupdf

ocr-pdf.ts — OCR for scanned PDFs

# OCR a scanned PDF
bun run scripts/ocr-pdf.ts scanned-doc.pdf

# OCR specific pages in German at high DPI
bun run scripts/ocr-pdf.ts --pages 1-5 --lang deu --dpi 600 scan.pdf

# JSON output with confidence scores
bun run scripts/ocr-pdf.ts --format json --output result.json scanned.pdf

--pages

--format

text

json

--lang

--dpi

--confidence-threshold

--output

Renders pages via

mupdf

tesseract.js

eng

fra

deu

spa

jpn

chi_sim

create-pdf.ts — PDF creation

# From plain text
bun run scripts/create-pdf.ts --from-text input.txt --output out.pdf

# From images (one per page)
bun run scripts/create-pdf.ts --from-images "photos/*.png" --output album.pdf

# From markdown
bun run scripts/create-pdf.ts --from-markdown doc.md --output report.pdf --page-size a4

--from-text

--from-images

--from-markdown

--output

--page-size

letter

a4

legal

--margin

--font-size

--title

--author

Exactly one of

--from-text

--from-images

--from-markdown

pdf-lib

merge-pdf.ts — Merge PDFs

# Merge two PDFs
bun run scripts/merge-pdf.ts --output merged.pdf chapter1.pdf chapter2.pdf

# Merge with page selections (semicolon-separated, one per input)
bun run scripts/merge-pdf.ts --output out.pdf --page-ranges "1-3;all;2-5" a.pdf b.pdf c.pdf

--output

--page-ranges

;

--bookmark

Pass two or more input PDFs as positional arguments. They are merged in order. Page ranges use semicolons between inputs:

"1-3;all;2-5"

split-pdf.ts — Split PDF

# One file per page
bun run scripts/split-pdf.ts report.pdf

# Split into 5-page chunks
bun run scripts/split-pdf.ts report.pdf --mode chunks --chunk-size 5 --output-dir ./split/

# Split by custom ranges
bun run scripts/split-pdf.ts report.pdf --mode ranges --ranges "1-3;4-6;7-10"

--mode

pages

ranges

chunks

--output-dir

--ranges

--chunk-size

--prefix

Checklist

• Identified the correct script for the operation
• Checked if PDF has selectable text (extract-text) or is scanned (ocr-pdf)
• Used

  --format json

  when structured output is needed downstream
• Verified output file exists and has expected content
• For merges: inputs provided in correct order
• For splits: verified all output files are present

Common Mistakes

"1-3;all;2-5"

--from-images "*.png"

*.png

Key Principles

1. Text before OCR — Always try

   extract-text.ts

   first. It's faster and more accurate for PDFs with embedded text. Only use

   ocr-pdf.ts

   when extract-text returns empty or garbled output.

2. JSON for pipelines — Use

   --format json

   when the output will be processed by another script or the agent. Use

   --format text

   when the output is for human reading.

3. Page ranges are 1-indexed — All scripts use 1-indexed page numbers in their

   --pages

   and

   --ranges

   flags. Internally they convert to 0-indexed for the PDF libraries.

4. Stderr for progress, stdout for data — Never mix diagnostics with output. All scripts write progress to stderr and data to stdout.