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.
fagus render invoice.html -o invoice.pdfGet 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.
fagus --version # fagus 0.1.0
fagus --help
fagus render --helpRender an HTML file#
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:
--attachattaches the file under its file name, with the file name as description and the relationshipSupplement. The MIME type comes from the extension:xml(text/xml),pdf,csv,json,txt,png,jpgandjpeg; any other file isapplication/octet-stream.--profileonly applies together with--factur-x.--createdreads 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:00becomes2026-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.--untaggedhas no effect with--accessibleor with--pdfa 2aand3a, 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:
fagus render invoice.html -o /dev/stdout | aws s3 cp - s3://invoices/2026-0042.pdfDiagnostics and timings go to standard error, one per line:
<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 loadedEach 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) |
$ 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 $?
1Examples#
A PDF with fonts of your own:
fagus render invoice.html -o invoice.pdf --font-dir resources/fontsA document whose style sheets and images lie in a parent directory (../css/print.css):
fagus render resources/pdf/invoice.html -o invoice.pdf --root resourcesAn archivable PDF with a file attached:
fagus render report.html -o report.pdf --pdfa 3b --attach data.csvA ZUGFeRD / Factur-X invoice that is also accessible, with a fixed date:
fagus render invoice.html -o invoice.pdf \
--factur-x invoice.xml --pdfa 3a --accessible \
--created 2026-11-01T08:00:00ZA check in a build job that fails on any ignored CSS or missing resource:
fagus render template.html -o /tmp/template.pdf --strictHow long each phase takes, as the median of 20 runs:
$ 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:
RAYON_NUM_THREADS=1 fagus render invoice.html -o invoice.pdfThe worker#
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.