Command-Line Interface

pdfik is the official command-line client for the PDFik API: render URLs and HTML to PDF from a terminal, a shell script or a CI job — no code to write. It is a single static binary for Linux, macOS and Windows (also a few-megabyte container image) and ships a wkhtmltopdf compatibility mode, so existing scripts keep working with an alias.

Source, issues and the complete reference: github.com/pdfik/cli.

Installation

# Linux: download, verify the checksum, install
curl -LO https://github.com/pdfik/cli/releases/latest/download/pdfik-linux-amd64
curl -LO https://github.com/pdfik/cli/releases/latest/download/checksums.txt
sha256sum --ignore-missing -c checksums.txt
chmod +x pdfik-linux-amd64 && sudo mv pdfik-linux-amd64 /usr/local/bin/pdfik
pdfik version

An API key is required — create one in the dashboard and export it as PDFIK_API_KEY. Prefer the variable over --api-key: flag values are visible to other processes and end up in shell history. See Authentication.

Quick Start

export PDFIK_API_KEY=sk_live_YOUR_KEY

pdfik url-to-pdf https://example.com                            # saves ./<job-id>.pdf
pdfik url-to-pdf https://example.com -o ./pdfs -f example.pdf   # -o directory, -f file name
pdfik html-to-pdf invoice.html -f invoice.pdf --format A4 --margin 10mm --margin-top 25mm
pdfik url-to-pdf https://example.com --test                     # free test run, sample PDF
pdfik url-to-pdf https://example.com -o - > example.pdf         # stream the PDF to stdout
pdfik status   <job-id>
pdfik download <job-id> -o ./pdfs                               # fetch a finished job later

One command does the whole job lifecycle: submit, poll until the render finishes (respecting the API's rate limits and Retry-After), download, and write the file atomically — a failed download never truncates a PDF from an earlier run. Flags are validated before anything is submitted, so a wrong format or a margin without a unit costs nothing.

html-to-pdf input is sanitized by the API (<style>, <script> and class attributes are stripped, relative assets are not resolved) — see Convert HTML to PDF. url-to-pdf renders with full fidelity; prefer it for styled documents.

Common Options

The full flag reference, including --api-url and the environment variables, is in the README.

Docker

docker run --rm --user "$(id -u):$(id -g)" -e PDFIK_API_KEY \
  -v "$PWD:/work" -w /work ghcr.io/pdfik/cli url-to-pdf https://example.com -f example.pdf

--user keeps the output file owned by you (the image runs as an unprivileged user); -o - streams to stdout and sidesteps file ownership entirely.

E-invoicing (Factur-X)

pdfik einvoice-to-pdf takes a UN/CEFACT Cross-Industry Invoice XML file (the Factur-X payload, UTF-8, up to 1 MB; - reads it from stdin) and writes a Factur-X / ZUGFeRD hybrid e-invoice: a PDF/A-3 file with the XML embedded as factur-x.xml. It runs the same submit → poll → download → atomic-write lifecycle as the other commands and uses the same exit codes. Available on every plan, Free included — the output is the same clean PDF/A-3. Endpoint reference: E-Invoicing.

pdfik einvoice-to-pdf <invoice.xml | -> [flags]

The page flags (--format, --landscape, --margin*, --no-background) do not apply here — an e-invoice's layout comes from its template. minimum and basicwl embed accompanying data only; the CLI prints a note when you pick one of them (silenced by -q).

export PDFIK_API_KEY=sk_live_YOUR_KEY

# Full example: EN 16931 profile, a saved template, a webhook, a named output file
pdfik einvoice-to-pdf invoice.xml \
  --profile en16931 \
  --template 550e8400-e29b-41d4-a716-446655440000 \
  --webhook https://yourserver.com/webhooks/pdf \
  -o ./invoices -f invoice-2026-001.pdf --timeout 2m

pdfik einvoice-to-pdf invoice.xml --test                  # free dry run, sample PDF
cat invoice.xml | pdfik einvoice-to-pdf - -o - > out.pdf  # stdin in, stdout out

Rejected requests cost nothing: invalid XML is answered with 422 EINVOICE_XML_INVALID (parsing, profile or XSD check failed) and an unknown --template id with 404 EINVOICE_TEMPLATE_NOT_FOUND; the CLI prints the message and exits with code 1. A job that fails after it was queued exits with code 3 and prints EINVOICE_FAILED.

wkhtmltopdf Compatibility Mode

pdfik wkhtmltopdf takes wkhtmltopdf's own flags and its <input> <output.pdf> arguments, so for most scripts the migration is an alias:

alias wkhtmltopdf='pdfik wkhtmltopdf'

wkhtmltopdf -s A4 -O Landscape --footer-center 'Page [page] of [topage]' \
  https://example.com out.pdf

# Pages behind a login (Pro plan and above)
wkhtmltopdf --username user --password pass https://intranet/report report.pdf

Every wkhtmltopdf flag is either mapped to the API, accepted with a warning (it has no effect in this pipeline) or refused with a reason (it would change the output) — never silently ignored. wkhtmltopdf --version and -h answer the way wrappers such as pdfkit and wicked_pdf expect. The flag-by-flag tables are in COMPATIBILITY.md.

Exit Codes

Scripts can branch on these; pdfik help lists them too.

Behaviour Worth Knowing

• The API key never leaves the API host. It is stripped from cross-host redirects, never logged, and plain http:// is refused unless you opt in explicitly.
• A job is never created — or charged — twice. A lost submit response is retried under one idempotency key.
• Ctrl-C is clean. No partial file is left behind and the in-flight job id is printed, so you can still pdfik download it.
• Windows: avoid redirecting -o - in Windows PowerShell 5.1 (powershell.exe re-encodes native output as text and corrupts the bytes) — let the CLI write the file, or redirect from cmd.exe / PowerShell 7+.

Next

• Testing — what a --test run does and does not do.
• Error Codes — the codes printed on exit code 3.
• SDKs — the same API from Node, Python and Java.