Skip to main content

Command-line Options

Prince may be called from the command-line with the following arguments:

    $ prince OPTIONS
        FILES
        [-o PDF]

Please note that on Windows, Prince can be called from the command-line by running the prince.exe file found in the Prince\engine\bin folder of the Prince installation:

    "C:\Program Files (x86)\Prince\engine\bin\prince.exe" OPTIONS
        FILES
        [-o PDF]

Examples​

    $ prince file.xml

Convert file.xml to file.pdf.

    $ prince doc.html -o out.pdf

Convert doc.html to out.pdf.

    $ prince http://example.com -o out.pdf

Convert the http://example.com webpage to out.pdf. Note that it is necessary to specify the output file when the input is a HTTP or HTTPS URL.

    $ prince
        -s style1.css
        -s style2.css
        input.xml
        -o output.pdf

Convert input.xml to output.pdf, applying two user style sheets.

    $ prince
        doc1.html
        doc2.html
        -o out.pdf

Combine doc1.html and doc2.html into a single PDF file, out.pdf.

    prince doc.html --raster-output=doc_%d.png

Process doc.html and rasterize the output to the series of files doc_1.png, doc_2.png, doc_3.png etc.

Specifying input and output​

The command-line must contain the name of the input file to process. An input filename consisting of a single hyphen "-" will cause Prince to read from the standard input stream.

The output file name can be specified on the command-line using the -o command-line option. An output filename consisting of a single hyphen "-" will cause Prince to write to the standard output stream.

If the output file name is omitted, the output will be placed in a file with the same name as the input, but with a PDF file extension.

It is necessary to specify the output file when the input is a HTTP or HTTPS URL.

Any of the --long command-line options can either be passed as a single command-line argument with an equals sign (=), or as two command-line arguments with space:

    --output=out.pdf
    --output out.pdf

The short command-line options are always passed as two command-line arguments, separated by a space:

    -o out.pdf

If the value of a command-line option contains a space or other command characters, the value has to be written between quotation marks.

If rasterization is used, the -o option is optional. If not specified, a PDF output will not be generated.

Options​

The command-line may include the options described below:

General Options​

-h, --help

Display usage and options.

--version

Display version information.

--credits

Display credits and acknowledgments.

--license-file=FILE

Pass a license file which is not in the standard location.

--license-key=KEY

Pass the license key on the command line - this is useful if you don't want to ship a product with the license key. The contents of the <signature> element must be deleted from your license file, and its value can then be passed as the value of this command-line option - but leave an empty <signature> element in place.

--show-license

Show information about the license used by Prince.

Logging Options​

-v, --verbose

Log informative messages.

--debug

Log debug messages.

--log=FILE

Append log messages to a file.

--no-warn-css-unknown

Do not warn about unknown CSS features.

--no-warn-css-unsupported

Do not warn about unsupported CSS features.

--no-warn-css

Do not warn about CSS problems - this option implies the above two options.

Input Options​

-i FORMAT, --input=FORMAT

Set input format [auto | xml | html | markdown].

-l, --input-list=FILE

Read input file list from specified file.

--baseurl=URL

Specify the base URL of the input document.

--remap=URL=DIR

Rather than retrieving documents beginning with URL get them from the local directory DIR. This option can be used multiple times to specify more than one remapping. It cannot be used with --fileroot.

note

Prince does not know which file to use when the path maps to a directory (in other words, an index file). If http://www.example.com/ is requested, and mapped to example-com it does not know whether to open example-com/index.html, example-com/index.php or any other file as this is site dependent. In this case Prince will report an error for that resource.

--fileroot=DIR

Specify the root directory for absolute filenames (deprecated).

--iframes

Enable HTML iframes.

--markdown-superscript

Enable superscript syntax in Markdown input. When enabled, carets (^text^) produce superscript (<sup>).

--markdown-subscript

Enable subscript syntax in Markdown input. When enabled, single tildes (~text~) produce subscript (<sub>) instead of strikethrough. Double tildes (~~text~~) still produce strikethrough.

--no-markdown-smart-typography

Disable smart typography in Markdown input. By default, Prince converts straight quotes to curly quotes, -- to an en-dash (–), --- to an em-dash (—), and ... to an ellipsis (…). This option disables that behavior.

--no-markdown-math

Disable automatic math rendering in Markdown input. By default, Prince renders math notation written with dollar signs ($...$ for inline, $$...$$ for display) using KaTeX. This option disables that behavior.

--xinclude

Enable XInclude and XML external entities (XXE). Note that XInclude only applies to XML files. To apply it to HTML files, the input format needs to be specified with the --input command-line option.

--xxe, --xml-external-entities

Enable XML external entities (XXE).

--xml-parse-huge

Enable loading very large XML documents. This option is only for Linux with libxml2 older than version 2.11.0.

--no-local-files

Disable access to local files.

Network Options​

--no-network

Disable network access (prevents HTTP downloads).

--no-redirects

Disable all HTTP and HTTPS redirects.

--auth-user=USER

Specify the username for HTTP authentication.

--auth-password=PASS

Specify the password for HTTP authentication.

--auth-server=HOST[:PORT]

Send username and password credentials to the specified server only. (The default is to send them to any server which challenges for authentication).

--auth-scheme=SCHEME

Send username and password credentials only for requests with the given scheme, either http or https

--auth-method=METHOD

Specify a comma separated list of HTTP authentication methods to enable. Valid entries are: basic, digest, ntlm and negotiate. The default is basic.

--auth=URL

Specify a URL with credentials for HTTP authentication: [SCHEME:]//USER:PASS@HOST[:PORT]. Unlike the preceding options, --auth may be used multiple times. The username and password must be percent-encoded.

--no-auth-preemptive

Do not send credentials to named servers until an authentication challenge is received. When multiple authentication methods are enabled, an initial request may be required to discover the methods supported by the remote site.

--http-proxy=PROXY

Specify the HTTP proxy server.

--http-timeout=SEC

Specify the HTTP timeout in seconds.

Specify a cookie that may be sent when making HTTP requests. The format is a Set-Cookie header field value, e.g. --cookie "name=value; domain=example.com". If you do not specify a domain for the cookie, it may not be sent. The exact behaviour depends on the underlying libcurl version.

Specify a file containing HTTP cookies. The cookies may be sent when making HTTP requests. The format of the file should be plain HTTP headers (Set-Cookie style) or the Netscape/Mozilla cookie file format.

--ssl-cacert=FILE

Specify an SSL certificate file.

--ssl-capath=PATH

Specify an SSL certificate directory.

--ssl-cert=FILE

Specify an SSL client certificate file. On MacOS, specify a PKCS#12 file containing a client certificate and private key. Client authentication is not supported on Windows.

--ssl-cert-type=TYPE

Specify the SSL client certificate file type (PEM, DER). The default is PEM. This option is not supported on MacOS or Windows.

--ssl-key=FILE

Specify an SSL private key file. This option is not supported on MacOS or Windows.

--ssl-key-type=TYPE

Specify the SSL private key file type (PEM, DER). The default is PEM. This option is not supported on MacOS or Windows.

--ssl-key-password=PASS

Specify passphrase for the private key.

--ssl-version=VERSION

Set the minimum version of SSL to allow. May be one of: default (let libcurl choose), tlsv1, tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3.

--ssl-no-revoke

Disable certificate revocation checks. This option only has effect on Windows.

--no-ssl-revoke-best-effort

Disable the default behaviour of ignoring certificate revocation checks that fail due to missing or offline distribution points for the revocation check lists. This option only has effect on Windows.

--insecure

Disable SSL verification (not recommended).

--no-parallel-downloads

Disable downloading multiple HTTP resources at once.

JavaScript Options​

-j, --javascript

Enable JavaScript in HTML documents.

--script=FILE

Run an external script.

--max-passes=NUMBER

Defines the maximal number of consequent layout passes - see The "Multi-Pass" Solution. The default is unlimited passes.

--pdf-script=FILE

Include a PDF script file to run when the PDF is opened. This is an accumulating option, and can be set multiple times.

--pdf-event-script=EVENT:FILE

Include a PDF script file to run on a specific event (will-close, will-save, did-save, will-print, did-print).

CSS Options​

-s FILE, --style=FILE

Apply an external style sheet. Note that repeating the option multiple times allows for applying multiple style sheets. They are applied in the order they are provided - and hence the last one will overwrite previous ones.

--media=MEDIA

Specify the media type (eg. print, screen).

--page-size=SIZE

Specify the page size (eg. A4, "155mm 190mm", etc). The syntax is the same as the size property in @page rules, which can take two values for horizontal and vertical dimensions. On the command-line it needs to be written between quotes as a single argument. See also Page size and Page Size Keywords.

--page-margin=MARGIN

Specify the page margin (eg. 20mm).

--no-author-style

Ignore author style sheets.

--no-default-style

Ignore default style sheets.

PDF Output Options​

-o FILE.PDF, --output=FILE.PDF

Specify the output PDF file.

--pdf-lang=LANG

Specify the PDF document's Lang entry in the document catalog - what is known as the Reading Options' Language.

--pdf-profile=PROFILE

Specify the PDF profile (see PDF Versions and Profiles) to use.

--pdf-output-intent=ICC

Specify the ICC profile to use.

--attach=FILE

Attach a file to the PDF.

--attach-data=FILE

Attach a file to the PDF with the AFRelationship key set to Data.

--attach-source=FILE

Attach a file to the PDF with the AFRelationship key set to Source.

--attach-alternative=FILE

Attach a file to the PDF with the AFRelationship key set to Alternative.

--attach-supplement=FILE

Attach a file to the PDF with the AFRelationship key set to Supplement.

--attach-unspecified=FILE

Attach a file to the PDF with the AFRelationship key set to Unspecified.

--no-artificial-fonts

Disable synthesis of missing bold/italic fonts.

--no-embed-fonts

Disable font embedding in PDF output.

--no-subset-fonts

Disable font subsetting in PDF output.

--no-system-fonts

Disable system fonts in PDF output. Only fonts defined with @font-face rules in CSS will be available.

--no-rename-duplicate-fonts

Disable renaming fonts with the same name (normally done to avoid a warning from Adobe Preflight).

--force-identity-encoding

Ensure that all fonts are encoded in the PDF using their identity encoding (directly mapping to glyph indices), even if they could have used MacRoman or some other encoding.

--no-compress

Disable compression of PDF output.

--no-object-streams

Disable PDF object streams.

--convert-colors

Convert colors to output intent color space.

--fallback-cmyk-profile=ICC

Set fallback ICC profile for uncalibrated CMYK.

--tagged-pdf

Enable tagged PDF.

--pdf-forms

Enable PDF forms.

--css-dpi=DPI

Changes the DPI of the "px" units in CSS, which defaults to 96dpi. It can be useful if you have a layout designed in pixels and you need to scale it down for print.

--pdf-dpi=auto | DPI

Defines the resolution the PDF will be printed and viewed with. The default is the value auto, which is equivalent to unspecified or infinite resolution. The value affects media queries or image srcset alternatives that depend on resolution, as well as the -prince-filter-resolution CSS property.

PDF Metadata Options​

--pdf-title=TITLE

Set PDF document title.

--pdf-subject=SUBJECT

Set PDF document subject.

--pdf-author=AUTHOR

Set PDF document author.

--pdf-keywords=KEYWORDS

Set PDF document keywords.

--pdf-creator=CREATOR

Set PDF document creator.

--pdf-xmp=XMP

Include additional XMP metadata in the PDF. The argument is an XMP file, from which the data is taken.

--pdf-xmp-metadata

Enable the XMP representation of HTML metadata even when the PDF profile does not require it.

PDF Encryption Options​

--encrypt

Encrypt PDF output.

--key-bits=NUM

Set encryption key size to either 40 or 128.

--user-password=PASS

Set PDF user password - max. 32 characters (Latin-1).

--owner-password=PASS

Set PDF owner password - max. 32 characters (Latin-1).

--disallow-print

Disallow printing of PDF output.

--disallow-copy

Disallow copying from PDF output.

--allow-copy-for-accessibility

Used together with --disallow-copy, for which it creates an exception by enabling text access for screen reader devices for the visually impaired.

--disallow-annotate

Disallow annotation of PDF output.

--disallow-modify

Disallow modification of PDF output.

--allow-assembly

Used together with --disallow-modify, for which it creates an exception. It allows the document to be inserted into another document or other pages to be added, but the content of the document cannot be modified.

Raster Output Options​

Rasterization is enabled with the --raster-output option below. When this is used the PDF output option (-o) is optional.

--raster-output=TEMPLATE

Enable raster output. The output files will be named based on the template. Prince will replace every %[WIDTH]d with the current page number. The optional WIDTH value gives the number of characters the page number should take within the file name. Smaller page numbers will be padded to the left with either spaces, or if the width begins with a zero, with zeros.

For example --raster-output=page_%02d.png will cause Prince to generate page_01.png, page_02.png, …, page_10.png, page_11.png etc.

Prince also accepts - meaning the standard output stream.

--raster-format=FORMAT

Set the format for the raster output. Valid formats are: auto (guess based on file extension, the default), png or jpeg. If Prince does not recognize the file extension, or --raster-output is -, then it is necessary to provide this option.

--raster-jpeg-quality=QUALITY

Set the level of JPEG compression when generating raster output in JPEG format. It takes a number between 0 and 100, default is 92.

--raster-pages=PAGE

Set the range of pages to be rasterize. Valid ranges are all (the default), first and NUM (a single page).

--raster-dpi=DPI

Set the resolution of raster output (The default is 96 dots per inch).

--raster-threads=NUM

Set the number of threads to use for multi-threaded rasterization. By default Prince chooses the number of threads based on the number of cores and hyperthreads your system provides.

--raster-background=BACKGROUND

Set the background - allowed values are transparent or white. It can be used when rasterizing to an image format that supports transparency (PNG, not JPG) and have a transparent background, so it can be composited with something else later.

Utility Options​

--scanfonts FILES...

Scan font files and create an @font-face at-rule for the selected fonts, which can be saved as a CSS file to use when defining a font family.

tip

When scanning variable fonts, Prince also illustrates all the variation axes of the font!

--font-specimen FONT

Create a sample PDF for the specified font, where FONT indicates a path (or URL) to a font file.

Advanced Options​

--http-header=HEADER

--user-agent=USER-AGENT

Custom HTTP headers can be passed to Prince in the format <Header>: <value>. To send multiple custom headers, use the option multiple times. The User-Agent header has its own command-line option. Please be aware that there can be unforseen side-effects when manipulating HTTP headers, including the User-Agent header.

--shell

The Prince shell will read JavaScript from standard input and execute it, basically allowing you to run scripts with Prince, which is handy for testing. It also allows to do conversions with the Prince.convertToFile and Prince.convertToBuffer methods, which are only accessible in shell mode.

--capture DIR

--replay DIR

The capture/replay system saves a copy of all the information in a job to a specified directory, conveniently allowing it to be replayed later for debugging purposes. See also The capture/replay system.

--control

The Prince Control Protocol is a synchronous bidirectional protocol that consists of a sequence of "chunks" sent via the standard input and output streams. For more details, please check the detailed documentation in the separate Prince Control Protocol chapter.

--job=FILE

The Job option allows to specify a Prince job in JSON format. For more details, please check the detailed documentation in the separate Prince Job JSON chapter.

--no-structured-log

--structured-log=LEVEL

The Structured Log option is a formatting option for Prince's output to stderr. Allowed level values are normal, quite, progress and buffered. For more details, please check the detailed documentation in the separate Structured Log chapter.

--fail-dropped-content

--fail-missing-resources

--fail-incorrect-references

--fail-stripped-transparency

--fail-missing-glyphs

--fail-pdf-profile-error

--fail-pdf-tag-error

--fail-invalid-license

--fail-safe

These nine Fail-Safe Options abort the creation of a PDF when one of the conditions is met - the last one enabling all of the previous ones. For more details, please check the detailed documentation in the separate Fail-Safe Options chapter.