> For the complete documentation index, see [llms.txt](https://docs.pd4ml.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pd4ml.com/pd4cmd-command-line-reference.md). # Pd4Cmd Command-Line Reference `com.pd4ml.tools.Pd4Cmd` is `pd4ml.jar`'s own `Main-Class` -- run directly with `java -jar`, no classpath assembly required (see the Programmer's Manual's [§4](/pd4ml-manual.md) for the fuller walkthrough this page complements). It covers four distinct jobs from one entry point: converting HTML to PDF, RTF, DOCX, or a raster image; editing an existing PDF in `-tools` mode; indexing TrueType/OpenType fonts; and launching the bundled GUI previewer. {% hint style="info" %} This reference was checked directly against the current `com.pd4ml.tools.Pd4Cmd` source and the usage banner it prints when run with no arguments, rather than transcribed from older documentation as-is. Three flags documented on earlier versions of this page -- `-noimagesplit`, `-smarttablesplit`, and `-protectpud` -- no longer exist in the current build and have been dropped below; several flags that do exist weren't previously documented at all and have been added (`-errorpolicy`, `-ligatures`, `-fitandcenterpage`, `-overlay`/`-underlay`/`-overlaypassword`, the `-log` alias for `-debug`, and DOCX/raster/`PdfSpec`-string support in `-outformat`). Always prefer running `java -jar pd4ml.jar` with no arguments over any static reference, including this one, for the definitive, always-current flag list for the exact build in use. {% endhint %} ## Minimum parameters ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar "https://pd4ml.com" 1200 ``` The two required positional arguments are the source (a `file:`, `http:`, or `https:` URL) and `htmlWidth` in pixels -- the virtual browser viewport width the source is laid out against. A third, optional positional argument names the target page format (a predefined name, or explicit `WIDTHxHEIGHT` in points); omitted, it defaults to A4. With no `-out`, the result streams to stdout rather than a file. ## A more complete conversion ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar "https://pd4ml.com" 1200 LETTER -bookmarks HEADINGS -pdfforms -debug 3 -out pd4ml.pdf ``` One correction versus older documentation of this same example: `-debug` now requires a numeric verbosity level (`0`-`5`) as its own argument -- a bare `-debug` with nothing after it is rejected outright (`invalid parameter: log level is missing`), rather than behaving as an on/off switch. ## PDF tools mode Passing `-tools` switches Pd4Cmd from HTML conversion into editing an existing PDF, given as the source in place of an HTML URL. ### Extracting a page range ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar -tools file:c:/docs/test.pdf -pagerange 2-3,5+ -out c:/docs/newdoc.pdf ``` ### Merging two PDFs ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar -tools file:c:/docs/test.pdf -merge file:c:/docs/tomerge.pdf after -out c:/docs/newdoc.pdf ``` ### Overlaying or underlaying one PDF onto another Not previously documented on this page: `-overlay`/`-underlay` composite one PDF's pages onto another's, entirely within tools mode -- no separate write-then-reread step needed: ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar -tools file:c:/docs/test.pdf -overlay file:c:/docs/stamp.pdf all all 128 -out c:/docs/newdoc.pdf ``` `srcScope` and `destScope` each accept either the keyword `all` or a page range/list such as `1-3,5`; opacity is `0`-`255`. `-underlay` takes the identical four arguments and paints beneath the base document's content instead of on top of it. `-overlaypassword` supplies the overlay/underlay source's password, alongside `-readpassword` (the primary input) and `-mergepassword` (an `-merge` input) for the other tools-mode password slots. `-merge` and `-overlay`/`-underlay` can't be combined in a single invocation; chain two separate calls, writing and re-reading the intermediate file, to apply both. ### Updating permissions ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar -tools file:c:/docs/test.pdf -permissions 28 -out c:/docs/newdoc.pdf ``` ### Reading document metadata ``` java -Djava.awt.headless=true -Xmx512m -jar pd4ml.jar -tools file:c:/docs/test.pdf -printpermissions -printauthor -printtitle -printpagenum ``` ## Indexing TTF fonts ``` java -Xmx512m -jar pd4ml.jar -configure.fonts [pd4fonts.properties location] ``` See the [Configuring PDF Fonts](/features/configuring-pdf-fonts.md) page for the fuller picture of when to reach for this versus the other font-indexing options. ## Launching the GUI ``` java -Xmx512m -jar pd4ml.jar -gui ``` Optionally followed by a URL to open immediately, rather than starting from the previewer's blank state. ## Full parameter reference | Flag | Purpose | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | *(positional, required)* Source document URL -- `file:`, `http:`, or `https:`. | | `` | *(positional, required)* Virtual browser viewport width, in pixels. | | `pageFormatName\|WxH` | *(positional, optional)* Target page format name, or explicit width x height in points. Default: `A4`. | | `-gui` | Launches the bundled GUI previewer/converter instead of converting from the command line. | | `-tools` | Switches to PDF-editing mode; the source is an existing PDF, not HTML. | | `-configure.fonts [loc]` | Indexes a TTF/OTF directory, writing `pd4fonts.properties` either alongside the fonts or to the given alternate location. | | `-xsl ` | Treats the source as XML and transforms it through the given XSL stylesheet first (`notesdefault` selects the bundled Domino/DXL stylesheet). | | `-usetmpfiles` | Extracts Base64-encoded Notes/DXL attachments to temporary files rather than passing them through the XSL transform inline. | | `-dumphtml` | Prints the post-XSL-transformation HTML to stdout, for debugging an `-xsl` conversion. | | `-errorpolicy ` | Controls how strictly malformed source HTML or non-conformant output is treated; see the Programmer's Manual's [§12](/pd4ml-manual.md). | | `-outformat ` | Selects the output format: `pdf` (default), `pdfa`, `pdfua`, `docx`, `rtf`, `rtfwmf`, `png8`, `png24`, `tiff`, or a combined `PdfSpec` string such as `"PDF1.7ext8 PDF/A-3a PDF/UA-1"`. | | `-pdfa` | Shorthand for requesting PDF/A-compliant output, equivalent to `-outformat pdfa`. | | `-bookmarks ` | Generates a PDF bookmark tree from `

`-`

` headings or from named anchors. | | `-orientation ` | Page orientation; `LANDSCAPE` rotates the target format 90°. Default: `PORTRAIT`. | | `-insets ` | Page margins, `unit` being `mm` or `pt`. Default: `10,10,10,10,mm`. | | `-bgcolor <#RRGGBB>` | Solid background color for every page. | | `-bgimage ` | Background image for every page, scaled to the full page area. | | `-watermark ` | Image watermark, positioned and sized in pixels with an opacity from 0-255. | | `-pdfforms` | Converts HTML form controls into interactive PDF (AcroForm) fields. | | `-multicolumn ` | Lays the document out in multiple columns per page, e.g. `3,10mm`. | | `-adjustwidth` | Measures the source's own natural width and uses that as `htmlWidth`, instead of the given value. | | `-fitapage` | Downscales the whole layout to fit a single page vertically, rather than paginating. | | `-fitandcenterpage` | As `-fitapage`, additionally centering the downscaled content on the page. | | `-nohyperlinks` | Suppresses conversion of HTML hyperlinks into PDF link annotations. | | `-author ` | Sets the PDF document-info Author field. | | `-title ` | Sets or overrides the document title (also usable as a `$[title]` placeholder value). | | `-header ''` | Page header content as HTML; supports `$[page]`, `$[total]`, `$[title]`. | | `-footer ''` | Page footer content as HTML; same placeholders as `-header`. | | `-addstyle ` | Applies an additional stylesheet to the source document; repeatable. | | `-cookie ` | Sends the given cookie with the source HTML's HTTP request; repeatable. | | `-param ` | Defines a dynamic placeholder value (and a named parameter) for the conversion; repeatable. | | `-encoding ` | Overrides the detected source document character encoding. | | `-ttf ` | TrueType/OpenType font directory to embed glyphs from. | | `-ttfrefsonly` | References fonts without embedding their glyph data in the output. | | `-kerning` | Applies the fonts' own kerning pairs. | | `-ligatures` | Builds compound glyphs (fi, fl, ...) where the active font defines them. | | `-threads ` | Enables asynchronous, concurrent resource loading with the given thread-pool size. | | `-pagerange ` | Limits which pages are written to output, e.g. `2+`, `1-2`, `even`, `odd`, `3-7,odd`. | | `-permissions ` | PDF access permissions, as a sum of individual permission bit values. | | `-password ` | Protects the output document with the given (owner) password. | | `-merge ` | Appends or prepends an existing PDF to the conversion result. | | `-overlay ` | *(tools mode)* Composites another PDF's pages on top of the source's. | | `-underlay ` | *(tools mode)* As `-overlay`, painted beneath the source's content instead. | | `-readpassword ` | *(tools mode)* Password for the primary input PDF. | | `-mergepassword ` | *(tools mode)* Password for the `-merge` input PDF. | | `-overlaypassword ` | *(tools mode)* Password for the `-overlay`/`-underlay` input PDF. | | `-printpermissions` | *(tools mode)* Prints the input PDF's permissions (as hex) to stdout. | | `-printauthor` | *(tools mode)* Prints the input PDF's Author field to stdout. | | `-printtitle` | *(tools mode)* Prints the input PDF's Title field to stdout. | | `-printpagenum` | *(tools mode, and regular conversion)* Prints the resulting page count to stdout. | | `-debug ` (alias `-log `) | Sets diagnostic verbosity, `0` (silent) through `5` (very verbose). | | `-out ` | Output file path. Omitted, output streams to stdout instead. | ## See also * [PD4ML Programmer's Manual](/pd4ml-manual.md) -- §4 introduces `Pd4Cmd` alongside the Java API and JSP taglib as the three ways to drive a conversion. * [Configuring PDF Fonts](/features/configuring-pdf-fonts.md) -- more on `-configure.fonts`/`-ttf` and the other ways to build a font mapping. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pd4ml.com/pd4cmd-command-line-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.