| name | pdf-tool |
| description | Inspect, search, read, render, create, fill, overlay, merge, split, batch-edit, and sign PDF files with the pdf-tool CLI. Use when an agent must work with PDF text, pages, tables, AcroForm fields, coordinates, or signatures while keeping reads bounded, emitting JSON, validating operations, and verifying the result. |
PDF Tool
Use pdf-tool instead of writing a one-off PDF manipulation script.
Prepare
- Run
command -v pdf-tool.
- If missing and this repository is available, run
uv tool install ..
Otherwise run uv tool install git+https://github.com/evrenverse/pdf-tool.
- Run
pdf-tool --version.
- Run
pdf-tool capabilities --json and pdf-tool doctor --json.
- Use
pdf-tool schema <name> when constructing structured input.
- Work on a copy unless the user explicitly wants an in-place edit.
Inspect before editing
- Run
pdf-tool info <file> --json.
- For forms, run
pdf-tool field-info <file> --json.
- Use
find, read --pages, or read --fields; avoid dumping the complete
document when a scoped read is enough.
Edit and verify
- Use
fill --validate-only before filling a form.
- Prefer
batch when fill, overlay, and signature operations belong in one
transaction.
- Never put a certificate passphrase in arguments or JSON. Use
--passphrase-file or the PDF_TOOL_CERT_PASSPHRASE secret environment
variable.
- Run
info, read, or field-info on the output.
- Report the output path and any font, rendering, or signature limitation.
Use zero-indexed page numbers. Keep an untouched copy of important documents.
Read references/cli.md when exact syntax, dependencies, or
exit behavior is needed.
