Command-line interface
The pdfspine command-line tool — its subcommands, flags, and example invocations.
Installing pdfspine registers a pdfspine console script (a small,
dependency-free argparse-based CLI in the spirit of PyMuPDF's python -m fitz
tool).
Usage
pdfspine <command> [options] <file.pdf>
pdfspine --versionSubcommands
| Command | Purpose |
|---|---|
info | Print document facts (page count, metadata, format, encryption). |
text | Extract text from a page range (text/json/html/xhtml/xml/blocks/words/dict/rawdict/rawjson). |
render | Rasterize pages to PNG at a given DPI or zoom factor. |
merge | Concatenate several PDFs into one. |
split | Split a PDF into per-page or per-range files. |
pages | Select / reorder / duplicate pages into a new file. |
images | Extract embedded image XObjects from a document. |
toc | Print the table of contents (bookmarks / outline). |
Page selectors (--pages, --ranges) use 1-based page numbers in a
1-3,5,8- style: comma-separated single pages or start-end ranges, where
either end may be omitted (-3 = pages 1..3, 8- = page 8 to the last).
Errors (file-not-found, malformed PDF, out-of-range pages, unsupported
features) print as a single pdfspine: <message> line on stderr with a
non-zero exit code — never a raw traceback.
Examples
# Document facts.
pdfspine info input.pdf
# Extract text from pages 1-3 to stdout.
pdfspine text --pages 1-3 input.pdf
# Extract text as JSON to a file.
pdfspine text --format json -o out.json input.pdf
# Render every page to PNG at 150 DPI into ./out/.
pdfspine render --dpi 150 -o out/ input.pdf
# Merge several PDFs.
pdfspine merge a.pdf b.pdf c.pdf -o merged.pdf
# Split into one file per page.
pdfspine split input.pdf -o parts/
# Split into ranges instead of one-per-page.
pdfspine split --ranges 1-3,4-6 input.pdf -o parts/
# Keep only pages 3, 1, 2 (reorder) into a new file.
pdfspine pages --select 3,1,2 input.pdf -o reordered.pdf
# Dump embedded images.
pdfspine images input.pdf -o images/
# Print the table of contents.
pdfspine toc input.pdfrender accepts either --dpi or --zoom (mutually exclusive; --zoom 1.0
is 72 DPI). -o/--output is a directory for render/split/images and a
file for merge/pages/text. Run pdfspine <command> --help for the full
flag list of any subcommand.
Each of these can also be scripted against the Python API directly — see Quickstart and Editing & saving.
Document generation
Create PDFs with pdfspine — render Markdown to a PDF with markdown_to_pdf, open images as PDF documents, and serialize any document to PDF bytes with convert_to_pdf.
Migrating from PyMuPDF
An honest account of pdfspine's PyMuPDF compatibility — the opt-in fitz shim, coverage at a glance, how gaps behave, the feature mapping, and what differs or is out of scope.