PDF to HTML Command line Reference

Conversion from PDF to HTML.

pdf2html [options] SOURCE
pdfcrowd pdf2html [options] SOURCE
pdf2html auth ACTION
pdf2html help [TOPIC|OPTION|CATEGORY]

Commands and Options

Conversion Input

SOURCE

Supply exactly one input source:

  • URL: an HTTP(S) URL.
  • File: the path to an existing local input file.
  • Standard input: - reads input bytes from a pipe or redirection.

Options may appear before or between sources. Use -- before a file name that starts with a dash.

Examples:
  • URL: pdf2html --output result.html https://example.com/input.pdf
  • Local file: pdf2html --output result.html input.pdf
  • Standard input: pdf2html --output result.html - < input.pdf

Output

Results go to standard output by default. Binary output requires a file, pipe, or redirection; only pdf2text writes directly to a terminal. Some converters produce ZIP archives containing their results. Diagnostics use standard error.

--output, -o FILE

Save the result to FILE. Use - for standard output.

An existing output file is replaced only after a successful conversion.

To send binary results to standard output, redirect them to a file or pipe them to another program.

Default:
standard output
Example:
  • pdf2html --output FILE SOURCE

--print-page-count

Print page count to stderr after conversion.

Configuration

If the default configuration file exists, conversions read it automatically. Conversions never save settings automatically. Run pdf2html help configuration to see the default file path. --config and --no-config are mutually exclusive.

Use a UTF-8 INI file with option-name = value lines and no [section] headings. Use the option names with hyphens and without leading dashes, for example debug-log instead of --debug-log. Lines starting with # or ; are comments.

For large HTML, CSS, or JavaScript values, keep the content in a separate UTF-8 file and use @{PATH} as the setting's value. The CLI reads the file's content without changing its whitespace or line breaks. Relative paths in an INI file are resolved from the config file's directory. On the command line, they are resolved from the current working directory. Do not put quotes around @{PATH} in the INI file; quote it when passing it on the command line.

Inline values can span multiple lines when each continuation line is indented more than the setting name. A blank line ends the value. Use a separate file for content that needs blank lines or exact formatting.

--config PATH

Read conversion defaults from PATH instead of the default file.

Command-line options override the settings in this file. This option applies to conversion settings; credentials are stored separately.

Examples:
  • pdf2html --config PATH --output FILE SOURCE
  • pdf2html --config ./defaults.ini -o result SOURCE

--no-config

Ignore saved conversion defaults for this command.

Command-line conversion options still apply. Saved credentials and environment variables still apply. The config file is left unchanged.

Example:
  • pdf2html --no-config --output FILE SOURCE

--init-config

Create a commented config file that you can edit.

Open the created file and remove the leading # from settings you want to use. Future conversions read the default file automatically.

Use --config PATH to create a file at another location. An existing file is left unchanged. This command does not perform a conversion.

Examples:
  • pdf2html --init-config [--config PATH]
  • pdf2html --init-config
  • pdf2html --init-config --config ./defaults.ini

--show-config

Show saved defaults and command-line overrides without converting.

Each setting shows whether it came from the config file or the command line. Other options use their API defaults.

Sensitive values and inline HTML, CSS, and JavaScript are hidden. No files are changed.

Examples:
  • pdf2html --show-config [options]
  • pdf2html --show-config
  • pdf2html --no-config --show-config

Authentication

For account setup and credential selection, see Authentication.

auth ACTION

Manage credentials shared by all converter commands.

ACTION: Choose login, status, or logout.

Usage:
pdf2html auth ACTION
pdfcrowd auth ACTION

auth login [--non-interactive]

Save your PDFCrowd username and API key for all converter commands.

Use both credential environment variables when set; otherwise prompt in an interactive terminal. The API-key prompt hides your input.

In a script, use --non-interactive to require environment credentials without prompting. This saves the account; it does not perform a conversion.

Usage:
pdf2html auth login [--non-interactive]
pdfcrowd auth login [--non-interactive]
auth login --non-interactive

This option applies only to auth login.

Require environment credentials when saving an account with auth login; never prompt.

Set both PDFCROWD_USERNAME and PDFCROWD_API_KEY before running this command. The account is saved for all converters. Missing credentials cause an error.

Example:
  • pdf2html auth login --non-interactive

auth status

Show which credentials will be used without revealing the API key.

This reads local settings; it does not verify the account with PDFCrowd.

Usage:
pdf2html auth status
pdfcrowd auth status

auth logout

Remove the saved account for all converter commands.

Credential environment variables still apply when set.

Usage:
pdf2html auth logout
pdfcrowd auth logout

Help and Version

help [TOPIC|OPTION|CATEGORY]

Show offline help for this converter.

Help does not load saved settings or credentials and does not contact the service.

TOPIC|OPTION|CATEGORY: Omit the argument for an overview. Supply one topic, option name (with or without --), or conversion category ID.

  • all: List every option.
  • categories: List help topics and conversion option groups.
  • syntax: Explain how to supply arguments.
  • configuration: Save and load conversion defaults.
  • authentication: Set up your PDFCrowd account.
  • input-output: Read inputs and save results.
  • exit-codes: Check whether a command succeeded.
Usage:
pdf2html help [TOPIC|OPTION|CATEGORY]
pdfcrowd help pdf2html [TOPIC|OPTION|CATEGORY]
Examples:
  • pdf2html help all
  • pdf2html help categories
  • pdf2html help --output
help --json

This option applies only to help.

Print help as JSON for scripts, integrations, and AI agents.

Includes option names, argument types, defaults, allowed values, authentication rules, and exit codes. Works offline.

Example:
  • pdf2html help --json

--help, -h

Show a summary of commands and options.

Use help all for every option, or help OPTION for details.

Example:
  • pdf2html --help

--version, -V

Show the PDFCrowd CLI version.

Example:
  • pdf2html --version

General Options

--pdf-password

Password to open the encrypted PDF file.

Syntax:
--pdf-password PASSWORD

--scale-factor

Set the scaling factor (zoom) for the main page area.

Syntax:
--scale-factor FACTOR
Constraint:
  • Must be a positive integer.
Default:
100

--print-page-range

Set the page range to print.

Syntax:
--print-page-range PAGES
Constraint:
  • A comma separated list of page numbers or ranges.
Examples:
  • Just the second page is printed: "2"
  • The first and the third page are printed: "1,3"
  • Everything except the first page is printed: "2-"
  • Just first 3 pages are printed: "-3"
  • Pages 3, 6, 7, 8 and 9 are printed: "3,6-9"

--dpi

Set the output graphics DPI. Higher values (144-300) improve quality but increase file size. Use 144 for web, 300 for print.

Availability:
Converter >= 20.10. See versioning.
Syntax:
--dpi DPI
Default:
144

--image-mode

Specify where the images are stored. Use separate files for better performance with large images or when serving images from a CDN. Use embedded for single-file portability.

Syntax:
--image-mode MODE
Default:
embed
Allowed Values:
  • embed — The images are embedded into the output HTML file.
  • separate — The images are saved to separate files. In this mode the output of the conversion is a zip file containing the HTML and all image files.
  • none — The images are ignored and not converted.

--image-format

Specify the format for the output images. Use PNG for lossless quality, JPG for smaller file sizes, or SVG for vector graphics.

Availability:
Converter >= 20.10. See versioning.
Syntax:
--image-format IMAGE_FORMAT
Default:
png
Allowed Values:
  • png
  • jpg
  • svg

--css-mode

Specify where the style sheets are stored. Use separate files for better browser caching and easier debugging. Use embedded for single-file HTML output.

Syntax:
--css-mode MODE
Default:
embed
Allowed Values:
  • embed — Style sheets are embedded into the output HTML file.
  • separate — Style sheets are saved to separate files. In this mode the output of the conversion is a zip file containing the HTML and all style sheets.

--font-mode

Specify where the fonts are stored. Use separate files for better browser caching and to reduce HTML file size. Use embedded for single-file portability.

Syntax:
--font-mode MODE
Default:
embed
Allowed Values:
  • embed — The fonts are embedded into the output HTML file.
  • separate — The font are saved to separate files. In this mode the output of the conversion is a zip file containing HTML and all font files.

--type3-mode

Set the processing mode for handling Type 3 fonts.

Availability:
Converter >= 24.04. See versioning.
Syntax:
--type3-mode MODE
Default:
raster
Allowed Values:
  • raster — Rasters Type 3 fonts into images, ensuring an exact visual representation in the HTML output.
  • convert — Attempts to convert Type 3 fonts to a web font, resulting in smaller file sizes with some possible visual discrepancies.

--split-ligatures

Converts ligatures, two or more letters combined into a single glyph, back into their individual ASCII characters.

Syntax:
--split-ligatures[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--custom-css

Apply custom CSS to the output HTML document to modify the visual appearance and layout. Use this to customize the styling of the converted HTML, adjust fonts, colors, spacing, or override default conversion styles.

Use !important in your CSS rules to prioritize and override conflicting styles.

Availability:
Converter >= 24.04. See versioning.
Syntax:
--custom-css CSS
Text from a file:
Use @{PATH} as the value to read UTF-8 text from a file. Relative paths in a config file are resolved from that file's directory; command-line paths are resolved from the current working directory. See Configuration for details.
Example:
  • Set the main background color to azure: "#page-container { background-color: azure; }"

--html-namespace

Add the specified prefix to all id and class attributes in the HTML content, creating a namespace for safe integration into another HTML document. This ensures unique identifiers, preventing conflicts when merging with other HTML.

Availability:
Converter >= 24.04. See versioning.
Syntax:
--html-namespace PREFIX
Constraint:
  • Start with a letter or underscore, and use only letters, numbers, hyphens, underscores, or colons.
Examples:
  • Namespace for first PDF embed: "pdf1_"
  • Custom namespace to avoid conflicts: "uniqueID123_"

--force-zip

Enforce the zip output format. Use when you want output as a zip archive even if single-file output would be possible.

Syntax:
--force-zip[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--title

Set the HTML title. The title from the input PDF is used by default.

Syntax:
--title TITLE

--subject

Set the HTML subject. The subject from the input PDF is used by default.

Syntax:
--subject SUBJECT

--author

Set the HTML author. The author from the input PDF is used by default.

Syntax:
--author AUTHOR

--keywords

Associate keywords with the HTML document. Keywords from the input PDF are used by default.

Syntax:
--keywords KEYWORDS

Miscellaneous

--debug-log

Turn on debug logging to troubleshoot conversion issues. Details about the conversion process, including resource loading, rendering steps, and error messages are stored in the debug log. Use this when conversions fail or produce unexpected results.

Syntax:
--debug-log[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--tag

Tag the conversion with a custom value for tracking and analytics. Use this to categorize conversions by customer ID, document type, or business unit. The tag appears in conversion statistics. A value longer than 32 characters is cut off.

Syntax:
--tag TAG
Example:
  • Track job in analytics: "client-1234"

--http-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTP scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--http-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Corporate proxy server: "myproxy.com:8080"
  • Direct IP proxy connection: "113.25.84.10:33333"

--https-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTPS scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--https-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Secure proxy for HTTPS: "myproxy.com:443"
  • Direct secure proxy IP: "113.25.84.10:44333"

API Client Options

--converter-version

Set the converter version. Different versions may produce different output. Choose which one provides the best output for your case.

Syntax:
--converter-version VERSION
Default:
24.04
Allowed Values:
  • 24.04 — Version 24.04.
  • 20.10 — Version 20.10.
  • 18.10 — Version 18.10.

--use-http

Specify whether to use HTTP or HTTPS when connecting to the PDFCrowd API.

Syntax:
--use-http[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--client-user-agent

Specify the User-Agent HTTP header the CLI sends to the PDFCrowd API.

Syntax:
--client-user-agent AGENT
Default:
pdfcrowd_cli_client/1.1.0 (https://pdfcrowd.com)

--proxy

Specify an HTTP proxy the CLI uses to connect to the PDFCrowd API.

Syntax:
--proxy HOST PORT USER_NAME PASSWORD

--retry-count

Specify the number of automatic retries when a 502 or 503 HTTP status code is received. The status code indicates a temporary network issue. This feature can be disabled by setting to 0.

Syntax:
--retry-count COUNT
Default:
1
Example:
  • Retry failed requests three times: 3