PDF to HTML Command Line Tool
Overview
Convert PDF pages to HTML from your terminal or shell scripts. The pdf2html command sends your input 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.
Convert a URL
Fetch a PDF from its URL and save the result locally:
pdf2html --output invoice.html \ https://your-server.com/invoice.pdf
Convert a File
Upload an existing logo.pdf file and save logo.html:
pdf2html --output logo.html \ logo.pdf
Configure a Conversion
Choose an Input
Supply one URL or local file. Use - to read bytes from stdin, including input
piped from another program. Remote URLs must be reachable from PDFCrowd's servers;
upload a local file or send its bytes for input on localhost or a private network.
See Conversion Input
for the supported forms.
For password-protected PDFs, supply the input document's password with
--pdf-password. This password is separate from your
PDFCrowd API key. Use --print-page-range to select pages.
Read Bytes from Stdin
Read logo.pdf through stdin and save logo.html:
pdf2html --output logo.html \ - < logo.pdf
Add Conversion Settings
Add options before the input. Command-line options override saved conversion defaults.
pdf2html --print-page-range=1,3 \ --output excerpt.html \ report.pdf
| Purpose | Options |
|---|---|
| Pages to convert | --print-page-range |
| Password-protected input | --pdf-password |
| Embedded or separate resources | --image-mode, --css-mode, --font-mode |
| Image format and resolution | --image-format, --dpi |
| Scale and styles | --scale-factor, --custom-css, --html-namespace |
| Consistent ZIP output | --force-zip |
The PDF password unlocks the input document; it is separate from your PDFCrowd API key.
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
By default, images, CSS and fonts are embedded in a single HTML file. The result preserves the PDF page layout; it does not reconstruct the original source HTML or create a responsive design.
Setting an image, CSS or font mode to separate produces a ZIP archive with the HTML and its resources. Save that result with a .zip extension, then extract it while preserving relative paths. Use --force-zip for consistent ZIP packaging.
Add --print-is-zipped-output to report whether the result is a ZIP archive.
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.
pdf2html 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
pdf2html 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 HTML as response.body and prints the
debug-log URL to stderr:
pdf2html --print-debug-log-url \ --debug-log \ --output response.body \ https://your-server.com/invoice.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 loaded | Check that the URL returns a PDF, rather than HTML or a login page, and is reachable from PDFCrowd's servers. For local files, check the path and read permissions. |
| The PDF requires a password | Set the input document's password with --pdf-password. |
| Images, fonts or styles are missing | If resource modes are set to "separate", extract the ZIP archive and retain its relative directory structure. |
| The layout does not adapt to the screen | The HTML preserves the PDF page layout. Responsive layouts require further work on the generated HTML and CSS. |
For help, contact support
with available diagnostics, the version from pdf2html --version,
and enough detail to reproduce the problem.