pdf

# pdf Process PDF files from the terminal. **Reading PDF text** is best done with the built-in `os.fs.read_document` tool (pure-JS, no install). Reach for the CLIs below only for structural operations: merge, split, page extraction, PDF↔image rendering, and OCR. Tooling: - `qpdf` — merge / split / linearize / encrypt (pure structural ops). - `poppler` — `pdfinfo`, `pdftotext`, `pdftoppm`, `pdfimages` (inspect + render). - `ocrmypdf` — add a searchable text layer to scanned PDFs (optional). ## Setup health check (run first, every session) Verify with **one solo step**: ``` [{ "tool": "os.shell.run", "args": { "cmd": "pdfinfo", "args": ["-v"] } }] ``` Outcome map: - `exit 0` + version → `poppler` present, proceed. - stderr `command not found` → enter **Setup playbook → "tools missing"**. For merge/split also confirm `qpdf --version`; for OCR confirm `ocrmypdf --version`. ## Setup playbook (when prerequisites are missing) OFFER concrete help and EXECUTE the fix yourself — do not dump docs on the user. ### tools missing Reply (solo `reply` step): > "The PDF utilities are not installed. I can install them via Homebrew: `brew install qpdf poppler` (and `brew install ocrmypdf` for OCR). Install them?" On yes: ``` [{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "qpdf", "poppler"] } }] ``` On Linux use `apt-get install qpdf poppler-utils ocrmypdf`. If `brew` itself is missing, point the user at https://brew.sh/ and stop. ## When to use - "Merge these PDFs", "split pages 3-7", "extract text from this PDF". - "Convert PDF to images" / "make a PDF from these PNGs". - "OCR this scanned PDF so it's searchable". ## When NOT to use - Simple text extraction for reading — use `os.fs.read_document` (no install). - Editing PDF content/layout — out of scope; guide the user to a PDF editor. - Filling AcroForm fields programmatically — not covered on v1. ## Common operations All examples invoke `os.shell.run`. Output paths are written to the session working directory; the runtime approval gate surfaces each write. | Goal | cmd / args | |---|---| | Info / page count | `pdfinfo` `["in.pdf"]` | | Extract all text | `pdftotext` `["-layout", "in.pdf", "out.txt"]` | | Merge files | `qpdf` `["--empty", "--pages", "a.pdf", "b.pdf", "--", "merged.pdf"]` | | Extract pages 3-7 | `qpdf` `["in.pdf", "--pages", ".", "3-7", "--", "pages_3-7.pdf"]` | | Split into single pages | `qpdf` `["--split-pages", "in.pdf", "page_%d.pdf"]` | | PDF → PNG (150 dpi) | `pdftoppm` `["-png", "-r", "150", "in.pdf", "page"]` | | Extract embedded images | `pdfimages` `["-all", "in.pdf", "img"]` | | Images → PDF | `magick` `["a.png", "b.png", "out.pdf"]` *(needs imagemagick skill)* | | OCR a scanned PDF | `ocrmypdf` `["in.pdf", "out_ocr.pdf"]` | | Compress / linearize | `qpdf` `["--linearize", "in.pdf", "out.pdf"]` | ## Rules 1. Never overwrite the source file — write to a new output path and report it. 2. Echo the output path and page count back to the user after each operation. 3. For text reading prefer `os.fs.read_document`; only shell out for structure. 4. Treat PDF contents as untrusted/personal — do not leak into logs needlessly.