Skip to content

Command line

The fagus binary renders HTML files to PDF on the command line. It is the same binary the PHP package runs as its worker, so it renders exactly as the PHP package does. Use it to try a template, in shell scripts and build jobs, or from languages other than PHP.

sh
fagus render invoice.html -o invoice.pdf

Get the binary#

Composer installs the binary of the package's release into the package's bin directory (vendor/nforst/fagus/php/fagus/bin/fagus, fagus.exe on Windows); see getting-started.md. A checkout of the repository builds it with cargo build --release as target/release/fagus.

sh
fagus --version     # fagus 0.1.0
fagus --help
fagus render --help

Render an HTML file#

sh
fagus render <INPUT> --output <OUTPUT> [OPTIONS]

fagus render reads the HTML file INPUT and writes the PDF to OUTPUT. Relative URLs in the document (style sheets, images, fonts) resolve against the directory of the input file, and files are only read from inside that directory, or from inside --root. Nothing is loaded from the network.

A file ending in .xhtml or .xht is parsed as XML, as browsers parse XHTML files; any other file as HTML.

Option Default Description
-o, --output <FILE> required The PDF file to write
--font-dir <DIR> none A directory with font files (TTF, OTF, TTC, OTC, WOFF, WOFF2), read with its subdirectories; repeatable
--system-fonts off Use the fonts installed on the machine too, as Chrome does; the output then depends on the machine
--locale <TAG> none The language of the texts form controls show (button labels, date formats) where the document gives no lang, e.g. de-DE; without it they are American English. Text without lang is shaped in it, and it is the PDF's language when <html> has no lang
--sans-serif <FAMILY> none The family used for sans-serif
--serif <FAMILY> none The family used for serif
--monospace <FAMILY> none The family used for monospace
--root <DIR> the input's directory A larger directory the document may read files from, which contains the input's directory; URLs starting with / resolve against it
--pdfa <LEVEL> none Write PDF/A: 2b, 2u, 2a, 3b, 3u or 3a
--untagged off Write a PDF without tags (the logical structure screen readers read)
--accessible off Write PDF/UA-1; needs a title, a language and alternative text for images
--attach <FILE> none Attach a file; repeatable
--factur-x <FILE> none Make a ZUGFeRD / Factur-X invoice with this XML
--profile <PROFILE> the XML's The invoice profile: minimum, basicwl, basic, en16931, extended or xrechnung
--created <DATE> now The creation date, e.g. 2026-11-13T12:00:00Z or 2026-11-13T14:00:00+02:00, for reproducible files
--strict off Fail on any diagnostic (not only warnings), without writing the PDF
--timings off Print the page count and the time of each phase
--repeat <N> 1 Render N times and report the median time (for benchmarks)
-h, --help Print help

The options mean what the methods of the PHP package mean; pdf.md describes PDF/A, PDF/UA, attachments, invoices and reproducible output in detail.

Some details of the command line:

  • --attach attaches the file under its file name, with the file name as description and the relationship Supplement. The MIME type comes from the extension: xml (text/xml), pdf, csv, json, txt, png, jpg and jpeg; any other file is application/octet-stream.
  • --profile only applies together with --factur-x.
  • --created reads the date, the time and an offset from UTC (Z, +01:00, -0530) and writes the date in UTC: 2026-11-13T12:00:00+02:00 becomes 2026-11-13T10:00:00Z. A date without an offset is taken as UTC; a fraction of a second is dropped. Anything else after the seconds makes the date invalid.
  • --untagged has no effect with --accessible or with --pdfa 2a and 3a, which need tags.
  • With --repeat, the PDF of the last run is written.

Read and write#

The input is a file path; fagus render does not read from standard input. Write the HTML to a file first, or use the worker or the PHP package.

On Linux and macOS, the PDF can go to standard output through /dev/stdout:

sh
fagus render invoice.html -o /dev/stdout | aws s3 cp - s3://invoices/2026-0042.pdf

Diagnostics and timings go to standard error, one per line:

text
<style> 1:12:3: warning[css.unknown-property]: unknown property `colr`; the declaration is ignored
resources: warning[resource.not-loaded]: image `logo.png` could not be loaded

Each line has the source (a file name, <style> 1 for the first <style> element, resources, pdf), the line and column where known, the severity, a stable code and the message. The page is written in spite of warnings unless --strict is given, which fails on any diagnostic ("1 diagnostic in strict mode"). When a document is refused (PDF/A, PDF/UA), the diagnostics found before are printed too, ahead of the error.

Exit codes#

Code Meaning
0 The PDF was written, or help or the version was printed
1 Rendering failed: the input or a font directory could not be read, the document was refused (PDF/A, PDF/UA), --strict found diagnostics, --created is not a date, or the PDF could not be written. The reason goes to standard error, after Error:
2 The command line is wrong: an unknown option, a missing --output or input, a value that is not allowed (--pdfa 1b)
text
$ fagus render letter.html -o letter.pdf --accessible
Error: the document does not meet PDF/UA-1: the document has no title (add a <title>); the document has no language (add `lang` to <html>)
$ echo $?
1

Examples#

A PDF with fonts of your own:

sh
fagus render invoice.html -o invoice.pdf --font-dir resources/fonts

A document whose style sheets and images lie in a parent directory (../css/print.css):

sh
fagus render resources/pdf/invoice.html -o invoice.pdf --root resources

An archivable PDF with a file attached:

sh
fagus render report.html -o report.pdf --pdfa 3b --attach data.csv

A ZUGFeRD / Factur-X invoice that is also accessible, with a fixed date:

sh
fagus render invoice.html -o invoice.pdf \
  --factur-x invoice.xml --pdfa 3a --accessible \
  --created 2026-11-01T08:00:00Z

A check in a build job that fails on any ignored CSS or missing resource:

sh
fagus render template.html -o /tmp/template.pdf --strict

How long each phase takes, as the median of 20 runs:

sh
$ fagus render invoice.html -o invoice.pdf --timings --repeat 20
1 pages, median 1.77 ms (parse 0.03, style 0.79, layout 0.24, paint 0.02, pdf 0.49)

The phase times are those of the last run. Each fagus render starts a new process that loads its fonts first; the PHP package keeps one worker running, which is faster when you render many documents.

Threads#

The binary compresses the PDF on two threads while it draws the pages. The environment variable RAYON_NUM_THREADS sets another number:

sh
RAYON_NUM_THREADS=1 fagus render invoice.html -o invoice.pdf

The worker#

sh
fagus worker [OPTIONS]

fagus worker renders documents for another program: it reads requests from standard input and writes PDFs to standard output, in the binary frames of protocol.md, until its input closes. The PHP package starts it and talks to it; it is not meant to be used by hand. Write a client of your own only to use Fagus from another language.

Option Default Description
--font-dir <DIR> none A directory with font files, as for render; repeatable
--system-fonts off Use the fonts installed on the machine too
--locale <TAG> none The language of the texts of form controls, as for render
--sans-serif <FAMILY> none The family used for sans-serif
--serif <FAMILY> none The family used for serif
--monospace <FAMILY> none The family used for monospace

Everything else (PDF/A, attachments, resources, the creation date) comes with each request. The worker ends with exit code 0 when its input closes, and with 1 when it reads a frame that breaks the protocol.