Configuration

Configuration

pdfcpu2 obtains settings and resources (config file, user fonts, trusted certificates) from a configuration root. Three modes exist:

Mode	Selected by	Behavior
auto	default	Uses config.yml, user fonts and trusted certs from the config root; creates missing resources on demand.
stateless	--conf disable	Built-in settings and the 14 core PDF fonts only. Never touches configuration files. Ideal for containers.
read-only	Go API only	Loads an existing file-backed configuration without writing. The CLI uses it internally for config inspect / config validate.

Config-root selection order: --conf PATH → PDFCPU_CONFIG_ROOT → OS default location.

Command line

pdfcpu2 config init                 # create missing resources at default root
pdfcpu2 config list                 # print the stored configuration
pdfcpu2 config inspect              # report mode, paths, policy (no writes)
pdfcpu2 config inspect --json       # machine readable
pdfcpu2 config validate             # validate schema and values
pdfcpu2 config reset                # replace with built-in defaults

Typical workflows:

# Service / container with a managed config root
pdfcpu2 --conf /srv/app-config config init
pdfcpu2 --conf /srv/app-config validate document.pdf

# Immutable container, zero file-system access
pdfcpu2 --conf disable validate document.pdf

config.yml highlights

The stored configuration covers validation strictness, encryption defaults, writer behavior and network limits. Notable entries for batch/AI pipelines:

• localImageRoot — the allowed directory for local images referenced by create / form JSON or CSV (empty = disabled).
• offline equivalent — or simply pass -o / --offline per invocation to disable all HTTP traffic.
• timeoutCRL, timeoutOCSP, preferredCertRevocationChecker — used by signatures validate.

Go API

package main

import (
	"context"
	"fmt"

	"github.com/huzpsb/pdfcpu2/pkg/api"
)

func main() {
	// auto mode at the default root
	conf, err := api.LoadConfiguration(api.ConfigurationOptions{})
	if err != nil {
		panic(err)
	}
	_ = conf

	// read-only inspection, nothing gets created or modified
	inspection, err := api.InspectConfiguration(api.ConfigurationOptions{Root: "/srv/app-config"})
	if err != nil {
		panic(err)
	}
	fmt.Println(inspection)
}

model.NewDefaultConfiguration() (see Go API) bypasses the config root entirely and gives you built-in defaults in memory — the quickest way to use pdfcpu2 as a library.