Merge, split, organize, compress, protect and watermark PDFs, or convert between PDFs and images, with a CLI built for scripts and AI agents, an agent skill, and a desktop app for everyone else. Free, open source, no ads, and 100% offline: your files are never uploaded anywhere.

pipx install pdf-tool-cli
pdf-tool compress report.pdf --target-mb 2

🧰 Tools

It never overwrites your files: outputs go next to the original (or to --output-dir) with a new name.

⌨️ Command line

pipx install pdf-tool-cli                      # or: uv tool install pdf-tool-cli
pdf-tool list --json                           # tools, accepted inputs and parameters
pdf-tool compress big.pdf --target-mb 2 --json # result as JSON
pdf-tool compress big.pdf --target-mb 2 --mode preserve   # keep text and links
pdf-tool merge a.pdf b.pdf c.pdf --output-name report
pdf-tool split doc.pdf --ranges "1-3, 5, 8-"
pdf-tool organize doc.pdf --pages "1,3-4,6-"   # delete pages 2 and 5
pdf-tool organize doc.pdf --pages "end-1"      # reverse the order
pdf-tool organize doc.pdf --pages "3,1-2@90,2" # move, rotate, duplicate
pdf-tool pdf2images doc.pdf --format png --dpi 300
printf '%s' "$PASSWORD" | pdf-tool protect doc.pdf --password-stdin

• Help: pdf-tool <tool> --help lists every flag.
• JSON for agents: --json prints a stable structure (ok, summary, outputs, per-file items, warnings, metrics such as sizes before and after compressing).
• Exit codes: 0 success · 1 processing failed · 2 invalid usage · 3 batch finished but some files failed.
• Passwords are read from stdin (--password-stdin) or the PDFTOOL_PASSWORD variable, never from arguments.
• Deleted pages really go: organize removes their content, form values and bookmarks from the new file, and never publishes a file that still holds them.
• Language: messages and output file names follow your system language; --lang en or --lang es overrides it (or set PDFTOOL_LANG).
• Compression modes: max (default) tries to reduce images first and only turns pages into images if that is the only way to reach the target (it warns you). preserve never does, so text, links and annotations are kept.

Requires Python 3.11+. pipx install 'pdf-tool-cli[gui]' also installs the desktop app (command pdftool).

🤖 Use it with AI agents

A skill teaches your agent to use pdf-tool instead of writing throwaway scripts: it asks before installing the CLI, runs the tools with --json and explains the result in your language. It follows the open Agent Skills format, so it works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and others.

Pick one way:

1. Claude Code (plugin, recommended): updates itself from main.

/plugin marketplace add juanMaAV92/pdf-tool
/plugin install pdf-tool@pdf-tool

2. Any agent, with skills (needs Node.js): detects your agents and copies the skill into each one's folder. Add -g to have it in every project; update it with npx skills update.

npx skills add juanMaAV92/pdf-tool

3. By hand: copy the skills/pdf-tool folder into your agent's skills folder (paths per agent). Copy it again to update.

In all three, the CLI is installed separately (pipx install pdf-tool-cli); if it is missing, the skill asks for permission to install it.

🖥️ Desktop app

The same eight tools with a simple interface, in English or Spanish, for macOS and Windows. No Python needed. To organize pages, you work on thumbnails: select them, then rotate, move, delete or duplicate, or drag a page to its place. The app opens PDFs of up to 1000 pages; the CLI has no limit.

• macOS: open the .dmg and drag pdf-tool to Applications. The app is not signed, so the first time go to System Settings → Privacy & Security and click Open Anyway.
• Windows: run the installer. If SmartScreen appears: More info → Run anyway.

Step-by-step guide, screenshots and FAQ: juanmaav92.github.io/en/pdf-tool. Every release publishes SHA256SUMS.txt so you can check the download.

🤝 Contributing

Issues and pull requests are welcome. Adding a tool means creating one folder: the app and the CLI discover it on their own. Translations are welcome too: copy pdftool/i18n/locales/en.json to <code>.json and translate it.

poetry install --all-extras   # Python 3.11+ and Poetry
poetry run pdftool            # the app
poetry run pdf-tool --help    # the CLI
poetry run pytest             # tests

Architecture, adding a tool and releases: AGENTS.md. What comes next: roadmap.

📄 License

The pdf-tool source code is MIT. It uses PyMuPDF, licensed under the AGPL, so the installers and the PyPI package, which include it, are distributed under the terms of the AGPL. Your documents are unaffected: they stay yours and never leave your computer.