PDF to PDF Command Line Tool
Overview
Merge, split, and modify PDF documents from your terminal or shell scripts with pdf2pdf. The command sends your inputs to PDFCrowd's servers and saves the result locally.
Installation
Install the command-line client with pip, or see other installation options.
python -m pip install pdfcrowd-cli
Quick Start
You can run the examples below without account setup. The CLI uses demo credentials unless you have configured your own API credentials. Update the input URLs and filenames as needed.
Commands use POSIX-shell syntax, as in Bash or Zsh, and save results in the current directory.
Merge PDFs
Merge first.pdf and second.pdf in that order into merged.pdf:
pdf2pdf --output merged.pdf \ first.pdf second.pdf
Add a Watermark
Apply watermark.pdf to proposal.pdf and save company_offer.pdf:
pdf2pdf --page-watermark=watermark.pdf \ --output company_offer.pdf \ proposal.pdf
Configure a Conversion
Add Input PDFs
Supply one or more existing local PDF files. The default action joins them in the order supplied. This converter accepts neither URLs nor stdin; save those inputs as local files before invoking it. See Conversion Input for the command syntax.
For encrypted inputs, use --input-pdf-password with the document password. This is separate from your API key and the passwords protecting the output PDF.
Add Conversion Settings
Add options before the input. Command-line options override saved conversion defaults.
Extract page 3 and pages 7 through the end of 13_pages.pdf into output.pdf:
pdf2pdf --action=extract \ --page-range=3,7- \ --output output.pdf \ 13_pages.pdf
| Purpose | Options |
|---|---|
| Join, interleave, extract or delete pages | --action, --page-range |
| Watermark and background | --page-watermark, --page-background, --multipage-watermark, --multipage-background |
| Optimize for progressive loading | --linearize |
| Output protection | --encrypt, --user-password, --owner-password, --no-copy, --no-print |
| Metadata and attachments | --title, --author, --use-metadata-from, --attachment |
Use "extract" with a page range to keep selected pages, or "delete" to remove them.
The "shuffle" action interleaves pages from the input PDFs.
See the command reference for all options and Configuration for saved defaults. For more tasks, browse the CLI examples.
Handle the Result
Choose an Output
Each invocation produces one PDF. To split a document into multiple files, run one extraction per output, as shown in the split example.
The examples save the result with
--output PATH.
The CLI replaces that file only after successful conversion, preserving an existing file
if conversion fails. Diagnostics go to stderr.
Omit --output or use --output - to send the result to stdout
for a pipe or shell redirection.
pdf2pdf refuses to send binary output directly to an interactive terminal.
Shell redirection opens or truncates its destination before the command runs and can leave
an empty or partial file on failure.
Handle Errors
Check the command's exit status before using its output: 0 means success and
a nonzero status means failure. In a shell script, $? immediately after the
conversion contains its status.
Service errors are written to stderr with the prefix PDFCrowd Error: and include
the status code, reason code, message, and documentation link when available.
These service codes differ from the command's process exit status.
See API status codes for service errors and
pdf2pdf help exit-codes for the process exit-code mapping.
Read Conversion Information
Add --print-page-count
to report the conversion's page count, or
--print-output-size
to report the output size in bytes.
Requested conversion information is printed to stderr, leaving stdout available for the result. See Output for all supported information flags.
Limits and Retries
Request rate and concurrency limits depend on your license. Control how quickly
your application submits conversions and how many it runs at once. A
429 response concerns request rate; a 430 response
concerns requests already in progress. The maximum upload size is 300 MB.
The CLI automatically retries a request once after an HTTP 502 or
503 response. Use --retry-count
to change the count, or set it to 0 to disable automatic retries.
Account for these retries when adding retries to a script or job runner.
Troubleshooting
Inspect a Conversion
Enable --debug-log and request
--print-debug-log-url.
This example saves the converted PDF as response.body and prints the
debug-log URL to stderr:
pdf2pdf --print-debug-log-url \ --debug-log \ --output response.body \ cover.pdf proposal.pdf
The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.
Common Problems
| Problem | Check |
|---|---|
| The PDF cannot be read | Check file paths, read permissions and whether each input is a valid PDF. For encrypted inputs, use --input-pdf-password. |
| Pages are missing or in the wrong order | Check the order of added PDFs, the selected action and the page range. Use the default join action to append documents, or "shuffle" to interleave their pages. |
| The watermark hides the document | A watermark is placed over the page. Use a transparent watermark or --page-background to place content behind the page. |
For help, contact support
with available diagnostics, the version from pdf2pdf --version,
and enough detail to reproduce the problem.