Home
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 --help with 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-markers to leave them out)
  • with -o, pictures are written to <name>_images next to the Markdown file and linked from it (--no-images to 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)