# Command line for scripts and AI agents

**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](Tools.md) 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) |

```sh
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`) |

```sh
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) |
