Skip to content
superPDF

PDF CLI

Run local tools from scripts and the terminal.

Runs on your computer. Files stay on your device; the agent or script can only use the folders you allow.

Run superPDF operations from scripts and the terminal. Files are processed on your computer, and outputs are always new files.

  1. Install the command-line tool

    The superpdf command runs the tools on your computer. It needs Node.js 22 or later. Install it once with npm:

    Available October 14, 2026. The install command below works from that day.

    Terminal
    npm install -g @superpdf/cli

# Check it works
superpdf help

  2. Run a command

    Terminal
    superpdf info report.pdf
superpdf merge a.pdf b.pdf --output combined.pdf
superpdf extract report.pdf --pages 1,3-5 --output selected.pdf
superpdf rotate report.pdf --pages 2 --angle 90 --output rotated.pdf
superpdf pipeline report.pdf --steps steps.json --output result.pdf

  3. Chain steps with a pipeline

    steps.json
    [
  { "action": "extract", "options": { "pages": "1-3" } },
  { "action": "rotate", "options": { "angle": 90 } },
  { "action": "labels", "options": { "text": "{page} / {total}" } }
]

High-accuracy reading

superpdf export can read the page images with LightOnOCR-3 (by LightOn, Apache-2.0), a small model made for documents that runs on your computer. It is much more accurate on scans, tables and math, and much slower: about 10 to 30 seconds a page on an Apple silicon Mac. Tables come back as HTML tables and math as LaTeX; the JSON output gives every block its position, and running headers, footers and page numbers are left out of the Markdown.

Terminal
superpdf model download
superpdf export scan.pdf --high-accuracy --output scan.md
superpdf export scan.pdf --high-accuracy --model 4b --output scan.md
  • Download: superpdf model download shows what it installs and its size, and asks first. The default model is 871 MB; --model 4b is 3.8 GB, more accurate and several times slower. The engine that runs them (about 471 MB on disk) is installed with it, from a lockfile with exact versions and checked hashes, with no install scripts. Every model file is checked against its SHA-256.
  • Where: ~/Library/Application Support/superPDF/models. superpdf model status shows what is installed; superpdf model remove deletes it.
  • Speed: it uses the graphics processor, one page at a time, and prints each page’s time and the time left. Press Ctrl+C to stop; nothing is written then.
  • Limits: like any OCR it can misread faded or handwritten text, so check the result.