CLI & configuration

PDF Server is configured only by command-line flags and environment variables (no config file). Every flag has an environment-variable equivalent, so this page doubles as the environment reference.

This table is maintained by hand for readability. A machine-generated version (app.ToMarkdown()) can be produced at build time to guarantee it never drifts — see Build & CI.

Commands

Command	Purpose
`server`	Run the long-running HTTP server.
`validate [filters…]`	Parse all templates and render every example; exit non-zero on failure. Filters are `<template>/<example>`.
`help`, `--version`	Help / version.

Global flags

Flag	Env	Default	Controls
`--log-level`	`LOG_LEVEL`	`info`	trace/debug/info/warning/error/fatal
`--log-format`	`LOG_FORMAT`	`text`	`text` or `json`
`--templates-dir, -t`	`TEMPLATES_DIR`	`templates/`	Templates directory
`--compositions-dir`	`COMPOSITIONS_DIR`	`compositions/`	Compositions directory
`--templates-reload-mode`	`TEMPLATES_RELOAD_MODE`	`none`	`none` or `always` (reload per request)
`--templates-recursive`	`TEMPLATES_RECURSIVE`	`false`	Load nested templates
`--wait-lifecycle-event`	`WAIT_LIFECYCLE_EVENT`	`load`	Default event awaited before printing
`--render-timeout`	`RENDER_TIMEOUT`	`30s`	Max duration per render
`--render-retry-attempts`	`RENDER_RETRY_ATTEMPTS`	`3`	Render attempts

Browser

Flag	Env	Default	Controls
`--browser-command` (`--chromium-command`)	`BROWSER_COMMAND`, `CHROMIUM_COMMAND`	`chromium`	Browser executable
`--browser-args` (`--chromium-args`)	`BROWSER_ARGS`, `CHROMIUM_ARGS`	headless flag set	Comma-separated args (`%{TMP_DIR}`, `%{TMP_ID}` substitutions)
`--browser-process-group-wait-timeout`	`BROWSER_PROCESS_GROUP_WAIT_TIMEOUT`	`10s`	Wait before SIGKILLing the browser process group

Render pool

Flag	Env	Default	Controls
`--render-pool-max-total`	`RENDER_POOL_MAX_TOTAL`	`1`	Max pooled browsers (and render workers)
`--render-pool-min-idle`	`RENDER_POOL_MIN_IDLE`	`1`	Min idle browsers
`--render-pool-max-idle`	`RENDER_POOL_MAX_IDLE`	`1`	Max idle browsers
`--render-pool-time-between-eviction`	`RENDER_POOL_TIME_BETWEEN_EVICTION`	`1h`	Eviction interval
`--render-pool-borrow-timeout`	`RENDER_POOL_BORROW_TIMEOUT`	`1m`	Max wait to borrow
`--render-pool-repay-timeout`	`RENDER_POOL_REPAY_TIMEOUT`	`5s`	Max wait to return

Factory

Flag	Env	Default	Controls
`--factory-type`	`FACTORY_TYPE`	`runner`	`runner` (browser per object) or `page` (tabs in one browser, Chromium only)
`--factory-max-usage-count`	`FACTORY_MAX_USAGE_COUNT`	`1000`	Reuse before recycle
`--factory-max-get-page-attempts`	`FACTORY_MAX_GET_PAGE_ATTEMPTS`	`20`	Attempts to get the initial page
`--factory-get-page-retry-delay`	`FACTORY_GET_PAGE_RETRY_DELAY`	`10µs`	Delay between attempts
`--factory-rpc-buffer-size`	`FACTORY_RPC_BUFFER_SIZE`	`8096`	CDP RPC buffer size

Tracing (OpenTelemetry)

Flag	Env	Default	Controls
`--tracing-enabled`	`TRACING_ENABLED`	`false`	Enable tracing
`--tracing-collector`	`TRACING_COLLECTOR`	`otel`	Collector type
`--tracing-service-name`	`TRACING_SERVICE_NAME`	`pdf-server`	Reported service name
`--tracing-propagators`	`TRACING_PROPAGATORS`, `OTEL_PROPAGATORS`	—	`tracecontext,baggage,b3,…`
`--otel-collector-protocol`	`OTEL_COLLECTOR_PROTOCOL`	`grpc`	`grpc` or `http`
`--otel-collector-grpc-addr`	`OTEL_COLLECTOR_GRPC_ADDR`	`localhost:4317`	OTLP/gRPC endpoint
`--otel-collector-http-addr`	`OTEL_COLLECTOR_HTTP_ADDR`	`localhost:4318`	OTLP/HTTP endpoint
`--tracing-sample-rate`	—	`1.0`	Sampling ratio
`--tracing-keep-status-trace`	—	`false`	Keep `/_status` spans
`--tracing-dial-timeout`	`TRACING_DIAL_TIMEOUT`	`15s`	Collector dial timeout

`server` flags

Flag	Env	Default	Controls
`--addr`	`SERVER_ADDR`	`:9999`	HTTP bind address
`--stop-timeout`	`SERVER_STOP_TIMEOUT`	`10s`	Graceful shutdown timeout
`--server-reuse-addr`	`SERVER_REUSE_ADDR`	`false`	`SO_REUSEADDR`
`--static-dir-enabled`	`STATIC_DIR_ENABLED`	`false`	Serve `/static/*` from disk
`--static-dir-path`	`STATIC_DIR_PATH`	`./app/server/static/`	Static dir path