Available in SumatraPDF for macOS and Linux. Coming to Windows.
SumatraPDF cli <command> reads and converts documents from a terminal, a script or an AI agent such as Claude Code or Codex.It works on every format SumatraPDF opens: PDF, EPUB, MOBI, FB2, XPS, DjVu, CHM and comic books (CBZ, CBR). The mupdf tools only read PDF and the formats mupdf knows.
- every command takes
--json: the output is then one JSON object - every command has
--helpwith examples - the files you give it are never changed: commands that make a file need
-o <output>and refuse to write over an input
On macOS the executable is inside the app:
/Applications/SumatraPDF.app/Contents/MacOS/SumatraPDF cli --help.Reading documents #
| Command | What it gives |
|---|---|
info <file> |
format, page count, page size, title, author, dates (ISO 8601) |
text <file> |
the text, page by page (pages separated by a form feed) |
markdown <file> [-o out.md] |
the document as Markdown: headings, lists, emphasis, code and pictures |
search <file> <text> |
every hit, with its page number, its box on the page and some context |
toc <file> |
the table of contents, with page numbers |
annotations <file.pdf> |
a PDF’s annotations; a highlight comes with the text it marks |
images <file> -o <folder> |
the pictures in the pages: a PDF’s JPEGs as they are, others as PNG |
verify <file.pdf> |
each signature: valid, untrusted (intact, signer not trusted here) or invalid; exit 0 only if all are valid |
render <file> -o page.png |
pages as images (PNG, JPEG, BMP or GIF, by the file’s extension) |
SumatraPDF cli info book.epub --json
SumatraPDF cli text paper.pdf --pages 3-5
SumatraPDF cli search thesis.pdf "error rate" --whole-word --json
SumatraPDF cli markdown report.pdf -o report.md
SumatraPDF cli render comic.cbz --pages 1-3 -o pages/<N>.jpg --dpi 96
Page ranges are like
1-3,7,10-N, where N is the last page.Markdown #
markdown is meant for reading a document with an LLM: it is far smaller than the page images, and page numbers come back exact.- a heading is a title from the table of contents, a short block in a font clearly larger than the body’s, or a line of bold on its own
- bold, italic, code, lists; lines are joined into paragraphs and words broken across lines put back together
- running headers and footers are left out
<!-- page N -->comes before each page (--no-page-markersto leave them out)- with
-o, pictures are written to<name>_imagesnext to the Markdown file and linked from it (--no-imagesto skip them)
Changing PDFs #
These always write a new PDF given with
-o.| Command | What it does |
|---|---|
pages keep <file.pdf> <range> |
keeps only these pages |
pages delete <file.pdf> <range> |
deletes these pages |
pages order <file.pdf> 3,1,2 |
the pages in this order (a page can repeat) |
pages rotate <file.pdf> <range> 90 |
turns pages clockwise by 90, 180 or 270 degrees |
merge a.pdf b.pdf ... |
the PDFs one after another |
split <file.pdf> -o <folder> |
a PDF per page, --every N pages or --ranges "1-3;4-N" group |
images-to-pdf <image> ... |
a page per image (JPEG, PNG, GIF, TIFF, WebP, …) |
annotate <file.pdf> highlight --text "words" |
words highlighted where they are (also underline, strikeout, squiggly; note --at x,y --contents ...; square --rect x,y,w,h) |
sign <file.pdf> --key me.pfx |
signed with the certificate and key in a .pfx (--key-password-env, --pages, --rect, --field) |
compress <file.pdf> |
a smaller copy, same quality |
decompress <file.pdf> |
a copy with uncompressed streams, for reading its insides |
encrypt <file.pdf> --new-password <pw> |
a copy that needs a password (AES-256) |
decrypt <file.pdf> --password <pw> |
a copy without the password |
watermark <file.pdf> <text> |
text across the middle of the pages (--opacity, --color, --size) |
number <file.pdf> |
page numbers (--format "Page {n} of {total}", --position bottom-center, --start) |
SumatraPDF cli pages keep scan.pdf 1-3,7 -o short.pdf
SumatraPDF cli merge a.pdf b.pdf -o both.pdf
SumatraPDF cli compress big.pdf -o small.pdf --json
SumatraPDF cli split book.pdf --ranges "1-12;13-40;41-N" -o chapters/
SumatraPDF cli annotate paper.pdf highlight --text "main result" -o marked.pdf
SumatraPDF cli sign contract.pdf --key me.pfx --key-password-env PFX_PASS --pages 2 --rect 72,700,200,60 -o signed.pdf
SumatraPDF cli watermark report.pdf DRAFT -o draft.pdf
SumatraPDF cli number book.pdf --pages 5-N --format "Page {n} of {total}" -o numbered.pdf
watermark and number take Latin text for now.Passwords #
An encrypted document needs
--password <pw>. --password-env <NAME> reads it from an environment variable instead, so it isn’t in the command line or the shell history. encrypt takes --new-password and --new-password-env the same way.For AI agents #
SumatraPDF cli agent-skill --install claude writes a skill to ~/.claude/skills/sumatrapdf/SKILL.md that tells Claude Code when and how to use the commands. --install codex and --install agents write it for Codex and other agents, and --install <dir> into <dir>/sumatrapdf. Without --install it prints the skill.JSON output and exit codes #
With
--json the output is one JSON object on stdout. An error is {"error": {"code": <exit code>, "message": "..."}}.| Exit code | Meaning |
|---|---|
| 0 | success |
| 1 | the command failed |
| 2 | wrong command line |
| 3 | the document doesn’t exist or can’t be opened |
| 4 | the document is encrypted: no password or a wrong one |
| 5 | the command doesn’t apply to this kind of document (e.g. a PDF tool on an EPUB) |