---
name: pdf-toolkit
description: "PDF toolkit - merge, split, extract text, convert to images. Runs locally."
metadata: { "openclaw": { "emoji": "📄" } }
---

# PDF Toolkit

Common operations on local PDF files: merge, split, extract text, convert. Prefers
tools already on the system, otherwise uses Python's `pypdf` (lightweight, pure
Python, installed on first use with `pip install pypdf`).

Everything runs on this machine. Nothing is uploaded.

## What it does

- **Merge**: combine several PDFs into one
- **Split**: break into pages, or pull out a page range
- **Extract text**: export contents as plain text for summarising or searching
- **Inspect**: page count and document metadata

## How to run it

Use the Bash tool. These examples use `pypdf` — cross-platform, no Office or
Acrobat needed.

```bash
# Ensure the dependency (first run only)
python -c "import pypdf" 2>/dev/null || pip install -q pypdf

# Merge a.pdf and b.pdf into merged.pdf
python - <<'PY'
from pypdf import PdfWriter
w = PdfWriter()
for f in ["a.pdf", "b.pdf"]:
    w.append(f)
w.write("merged.pdf"); w.close()
print("merged -> merged.pdf")
PY

# Extract all text
python - <<'PY'
from pypdf import PdfReader
r = PdfReader("input.pdf")
print("\n".join((p.extract_text() or "") for p in r.pages))
PY

# Pull out pages 1-3 into sub.pdf
python - <<'PY'
from pypdf import PdfReader, PdfWriter
r = PdfReader("input.pdf"); w = PdfWriter()
for i in range(0, 3):
    w.add_page(r.pages[i])
w.write("sub.pdf"); w.close()
print("extracted pages 1-3 -> sub.pdf")
PY
```

## Working notes

- Check the file exists first with `ls`, and get the page count with
  `python -c "from pypdf import PdfReader; print(len(PdfReader('x.pdf').pages))"`
- Scanned PDFs are images — text extraction returning nothing is expected.
  Tell the user it needs OCR rather than reporting an empty result as success.
- Write output next to the source file, and tell the user the filename you created.