CLI Reference

The printwell command-line tool provides access to all printwell features.

Global Options

printwell [OPTIONS] <COMMAND>

Options:
  -v, --verbose    Increase verbosity (-v, -vv, -vvv)
  -q, --quiet      Suppress output
  -h, --help       Print help
  -V, --version    Print version

Commands

convert

Convert HTML to PDF.

printwell convert [OPTIONS] <INPUT>

Arguments:

<INPUT> - HTML file path, URL, or - for stdin

Options:

Option	Description	Default
`-o, --output <FILE>`	Output PDF file path	-
`--page-size <SIZE>`	Page size: A3, A4, A5, Letter, Legal, Tabloid	A4
`--width <LENGTH>`	Custom page width (e.g., “210mm”)	-
`--height <LENGTH>`	Custom page height (e.g., “297mm”)	-
`--margin <MARGINS>`	Page margins (e.g., “10mm” or “10mm,20mm,10mm,20mm”)	10mm
`--landscape`	Use landscape orientation	false
`--no-background`	Don’t print background graphics	false
`--scale <FACTOR>`	Scale factor	1.0
`--page-ranges <RANGES>`	Pages to print (e.g., “1-5,8”)	All
`--header <HTML>`	Header HTML template	-
`--footer <HTML>`	Footer HTML template	-
`--timeout <DURATION>`	Resource fetch timeout	30s
`--font <SPEC>`	Custom font (format: “family:path”)	-

Metadata Options:

Option	Description
`--title <TEXT>`	PDF document title
`--author <TEXT>`	PDF document author
`--subject <TEXT>`	PDF document subject
`--keywords <TEXT>`	PDF document keywords (comma-separated)
`--creator <TEXT>`	PDF creator application name
`--producer <TEXT>`	PDF producer name

Form Detection Options:

Option	Description
`--detect-forms`	Detect HTML form elements and output their positions
`--convert-forms`	Auto-convert detected HTML forms to native PDF form fields
`--forms-output <FILE>`	Output detected form elements to JSON file
`--validate-forms <FILE>`	Validate detected forms against rules JSON file
`--validation-output <FILE>`	Output validation results to JSON file

Boundary Extraction Options:

Option	Description
`--boundaries <SELECTORS>`	CSS selectors for boundary extraction (comma-separated)
`--boundaries-output <FILE>`	Output boundaries to JSON file

Examples:

# Basic conversion
printwell convert report.html -o report.pdf

# From URL with custom page size
printwell convert https://example.com -o example.pdf --page-size Letter

# Landscape with custom margins
printwell convert input.html -o output.pdf --landscape --margin "25mm,10mm,25mm,10mm"

# With header and footer
printwell convert input.html -o output.pdf \
    --header '<div style="font-size:9px">Header</div>' \
    --footer '<div style="font-size:9px">Page <span class="pageNumber"></span></div>'

# With custom fonts and metadata
printwell convert input.html -o output.pdf \
    --font "MyFont:./fonts/custom.ttf" \
    --title "My Document" \
    --author "John Doe"

# From stdin
cat template.html | printwell convert - -o output.pdf

convert-batch

Convert multiple HTML files to PDF in batch.

printwell convert-batch [OPTIONS] <INPUTS>...

Options:

Option	Description	Default
`-o, --output-dir <DIR>`	Output directory for generated PDFs	.
`--workers <NUM>`	Maximum concurrent conversions	4
`--page-size <SIZE>`	Page size	A4
`--background`	Print background colors and images	false
`--landscape`	Use landscape orientation	false

Examples:

# Convert multiple files
printwell convert-batch file1.html file2.html file3.html -o ./output

# With 8 parallel workers
printwell convert-batch *.html -o ./pdfs --workers 8

watermark

Add watermark to PDF. Requires the watermark feature.

printwell watermark [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description	Default
`-o, --output <FILE>`	Output PDF file path	Required
`--text <TEXT>`	Watermark text	-
`--image <FILE>`	Watermark image path (PNG or JPEG)	-
`--position <POS>`	Position: center, top-left, top-center, top-right, middle-left, middle-right, bottom-left, bottom-center, bottom-right, or “x,y”	center
`--rotation <DEG>`	Rotation in degrees (counter-clockwise)	0
`--opacity <FLOAT>`	Opacity (0.0-1.0)	0.3
`--font-size <PT>`	Font size in points	72
`--color <COLOR>`	Color as hex (e.g., “#FF0000”) or name (e.g., “gray”)	gray
`--foreground`	Place watermark in foreground	false
`--pages <SELECTION>`	Pages: “1,3,5”, “1-10”, “odd”, “even”, “first”, “last”	all
`--scale <FACTOR>`	Scale factor for the watermark	1.0

Examples:

# Text watermark
printwell watermark document.pdf -o watermarked.pdf --text "DRAFT"

# Diagonal confidential watermark
printwell watermark document.pdf -o watermarked.pdf \
    --text "CONFIDENTIAL" \
    --rotation 45 \
    --opacity 0.2 \
    --color "#FF0000"

# Image watermark
printwell watermark document.pdf -o watermarked.pdf \
    --image logo.png \
    --position bottom-right \
    --opacity 0.5

# Watermark only odd pages
printwell watermark document.pdf -o watermarked.pdf \
    --text "SAMPLE" \
    --pages odd

bookmarks

Add or extract bookmarks from a PDF. Requires the bookmarks feature.

printwell bookmarks [OPTIONS] <INPUT>

Options:

Option	Description
`-o, --output <FILE>`	Output PDF file (for adding bookmarks)
`--add <SPEC>`	Add bookmark (format: “title:page” or “title:page:y_position” or “title:page:y_position:parent_index”)
`--extract <FILE>`	Extract bookmarks to JSON file
`--from-json <FILE>`	Add bookmarks from JSON file
`--format <FMT>`	Output format for extraction: text, json

Examples:

# Add bookmarks inline
printwell bookmarks document.pdf -o output.pdf \
    --add "Chapter 1:1" \
    --add "Chapter 2:5" \
    --add "Chapter 3:10"

# Add bookmarks from JSON
printwell bookmarks document.pdf -o output.pdf --from-json bookmarks.json

# Extract bookmarks to JSON
printwell bookmarks document.pdf --extract bookmarks.json

# Extract bookmarks as text
printwell bookmarks document.pdf --extract - --format text

annotate

Add, list, or remove annotations from a PDF. Requires the annotations feature.

printwell annotate [OPTIONS] <INPUT>

Options:

Option	Description
`-o, --output <FILE>`	Output PDF file
`--highlight <SPEC>`	Add highlight (format: “page:x:y:width:height” or “page:x:y:width:height:color”)
`--note <SPEC>`	Add sticky note (format: “page:x:y:contents”)
`--underline <SPEC>`	Add underline (format: “page:x:y:width:height”)
`--strikeout <SPEC>`	Add strikeout (format: “page:x:y:width:height”)
`--square <SPEC>`	Add rectangle (format: “page:x:y:width:height:color”)
`--list`	List existing annotations
`--remove`	Remove all annotations (or specific types)
`--page <NUM>`	Page to filter for remove operation (1-indexed)
`--color <HEX>`	Default annotation color
`--format <FMT>`	Output format for list: text, json

Examples:

# Add highlight
printwell annotate document.pdf -o annotated.pdf \
    --highlight "1:100:200:150:20"

# Add sticky note
printwell annotate document.pdf -o annotated.pdf \
    --note "1:50:100:Review this section"

# List annotations
printwell annotate document.pdf --list --format json

# Remove all annotations
printwell annotate document.pdf -o cleaned.pdf --remove

encrypt

Encrypt PDF with password protection. Requires the encrypt feature. Commercial license required.

printwell encrypt [OPTIONS] <INPUT> -o <OUTPUT>

Password Options:

Option	Description
`--owner-password <PASS>`	Owner password (visible in process listings)
`--owner-password-file <FILE>`	Read owner password from file (more secure)
`--owner-password-env <VAR>`	Read owner password from environment variable
`--user-password <PASS>`	User password (visible in process listings)
`--user-password-file <FILE>`	Read user password from file (more secure)
`--user-password-env <VAR>`	Read user password from environment variable

Permission Options:

Option	Description
`--allow-print`	Allow printing
`--allow-print-hq`	Allow high-quality printing
`--allow-copy`	Allow copying text and graphics
`--allow-accessibility`	Allow extracting text for accessibility
`--allow-modify`	Allow modifying the document
`--allow-annotate`	Allow adding annotations
`--allow-assemble`	Allow assembling the document
`--allow-fill-forms`	Allow filling form fields
`--allow-all`	Allow all permissions

Other Options:

Option	Description	Default
`--algorithm <ALG>`	aes256, aes128, or rc4	aes256

Examples:

# Basic encryption with owner password from file
printwell encrypt document.pdf -o encrypted.pdf --owner-password-file secret.txt

# With user password and restrictions
printwell encrypt document.pdf -o encrypted.pdf \
    --owner-password-env OWNER_PASS \
    --user-password-env USER_PASS \
    --allow-print --allow-fill-forms

decrypt

Decrypt a password-protected PDF. Requires the encrypt feature. Commercial license required.

printwell decrypt [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description
`--password <PASS>`	Password (visible in process listings)
`--password-file <FILE>`	Read password from file (more secure)
`--password-env <VAR>`	Read password from environment variable

sign

Digitally sign a PDF. Requires the signing feature. Commercial license required.

printwell sign [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description	Default
`--certificate <FILE>`	PKCS#12 certificate file (.p12/.pfx)	Required
`--password <PASS>`	Certificate password (visible in process listings)	-
`--password-file <FILE>`	Read password from file (more secure)	-
`--password-env <VAR>`	Read password from environment variable	-
`--reason <TEXT>`	Reason for signing	-
`--location <TEXT>`	Location of signing	-
`--level <LEVEL>`	PAdES level: B, T, LT, LTA	B
`--timestamp-url <URL>`	Timestamp server URL	-
`--visible <FIELD>`	Visible signature field name	-
`--position <SPEC>`	Visible signature position (format: “page:x,y,w,h”)	-
`--certify`	Create a certification signature	false
`--mdp <LEVEL>`	MDP permissions: 1=no-changes, 2=form-filling, 3=annotations	2

Examples:

# Invisible signature
printwell sign document.pdf -o signed.pdf \
    --certificate certificate.p12 \
    --password-file pass.txt \
    --reason "Approved" \
    --location "New York"

# Visible signature with timestamp
printwell sign document.pdf -o signed.pdf \
    --certificate certificate.p12 \
    --password-env CERT_PASS \
    --visible "Signature1" \
    --position "1:400,50,150,50" \
    --timestamp-url "http://timestamp.digicert.com"

# Certification signature
printwell sign document.pdf -o certified.pdf \
    --certificate certificate.p12 \
    --password-file pass.txt \
    --certify \
    --mdp 2

verify

Verify PDF signatures. Requires the signing feature. Commercial license required.

printwell verify [OPTIONS] <INPUT>

Options:

Option	Description	Default
`--format <FMT>`	Output format: text, json	text
`--use-system-trust`	Use system trust store for certificate chain validation	false

list-fields

List signature fields in a PDF. Requires the signing feature. Commercial license required.

printwell list-fields [OPTIONS] <INPUT>

Options:

Option	Description	Default
`--format <FMT>`	Output format: text, json	text

forms

Add form fields to PDF. Requires the forms feature. Commercial license required.

printwell forms [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description
`--text-field <SPEC>`	Add text field (format: “name:page:x,y,w,h”)
`--checkbox <SPEC>`	Add checkbox (format: “name:page:x,y,size”)
`--dropdown <SPEC>`	Add dropdown (format: “name:page:x,y,w,h:opt1,opt2,…”)
`--signature-field <SPEC>`	Add signature field (format: “name:page:x,y,w,h”)

Examples:

# Add form fields
printwell forms document.pdf -o form.pdf \
    --text-field "name:1:50,700,200,20" \
    --text-field "email:1:50,650,200,20" \
    --checkbox "agree:1:50,600,15" \
    --signature-field "signature:1:50,500,200,50"

pdfa-validate

Validate PDF/A compliance. Requires the pdfa feature. Commercial license required.

printwell pdfa-validate [OPTIONS] <INPUT>

Options:

Option	Description	Default
`--level <LEVEL>`	PDF/A level: 1b, 1a, 2b, 2u, 2a, 3b, 3u, 3a	2b
`--format <FMT>`	Output format: text, json	text

pdfa-convert

Add PDF/A metadata to a PDF. Requires the pdfa feature. Commercial license required.

printwell pdfa-convert [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description	Default
`--level <LEVEL>`	PDF/A level: 1b, 1a, 2b, 2u, 2a, 3b, 3u, 3a	2b
`--title <TEXT>`	Document title	-
`--author <TEXT>`	Document author	-

pdfua-validate

Validate PDF/UA accessibility compliance. Requires the pdfua feature. Commercial license required.

printwell pdfua-validate [OPTIONS] <INPUT>

Options:

Option	Description	Default
`--level <LEVEL>`	PDF/UA level: 1, 2	1
`--format <FMT>`	Output format: text, json	text

pdfua-convert

Add PDF/UA accessibility metadata to a PDF. Requires the pdfua feature. Commercial license required.

printwell pdfua-convert [OPTIONS] <INPUT> -o <OUTPUT>

Options:

Option	Description	Default
`--level <LEVEL>`	PDF/UA level: 1, 2	1
`--title <TEXT>`	Document title	-
`--language <LANG>`	Document language (BCP 47 format, e.g., “en-US”)	en

info

Display PDF/renderer information.

printwell info [OPTIONS] [INPUT]

Arguments:

[INPUT] - Optional PDF file to inspect

Options:

Option	Description
`--renderer`	Show renderer information

Examples:

# Show renderer info
printwell info --renderer

# Inspect PDF file
printwell info document.pdf

Output:

printwell 0.1.0
Chromium: 120.0.6099.0
Skia: m120
Build: release

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Input file not found
4	Output write error
5	Conversion error
6	Validation failed

Keyboard shortcuts

printwell