Merge, split, compress, protect and watermark PDFs, or turn images into PDFs, 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-"
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.
• 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 six tools with a simple interface, in English or Spanish, for macOS and Windows. No Python needed.

• 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. The roadmap lists what comes next.

poetry install --all-extras   # includes Flet (the [gui] extra) for the app
poetry run pdftool            # opens the app
poetry run pdf-tool --help    # the CLI
poetry run pytest             # tests

git tag vX.Y.Z
git push origin vX.Y.Z

poetry run flet build macos --project pdf-tool --product pdf-tool     # -> build/macos/pdf-tool.app
poetry run flet build windows --project pdf-tool --product pdf-tool   # -> build/windows/

📄 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.