Configuration

The precedence is built-in defaults, a JSON configuration file, then repeated --set KEY=VALUE overrides for the current invocation. The default file is .afpdf/config.json in the current directory; --config PATH selects another JSON file. There is no parent-directory search. An absent default file uses defaults, while an explicitly selected missing file fails extraction.

# Inspect effective settings without creating a file.
afpdf config show
afpdf config get extract.processing.remove_page_furniture

# Explicitly save an override for subsequent invocations.
afpdf config set extract.processing.remove_page_furniture false
afpdf config set output.basic true

# Override only this extraction; the file remains unchanged.
afpdf extract article.pdf --set extract.processing.merge_across_pages=false

# Remove a saved override and restore its default.
afpdf config unset output.basic

Reads and extraction do not create configuration files. config set stores only overrides; unknown keys, invalid types, and invalid limits are rejected before a write. config unset restores the schema default. AFDATA’s document layer owns dot paths, type-directed coercion, source-preserving edits and atomic save. --value-type is available for explicit string/number/bool/JSON/null values. New fields are exposed by the typed model without adding CLI flags.

The three sections are extract (the SDK’s ExtractOptions, including extract.processing), execution (the engine location, isolation and its limits), and output (basic, article, text). The worker receives the resolved extraction request and does not load the parent CLI’s configuration itself. SDK callers continue to pass typed options explicitly.

Output selection

Key	Default	Purpose
`output.article`	`true`	Organized blocks, source spans, and removed furniture
`output.text`	`true`	Continuous text derived from the article
`output.basic`	`false`	Native text, glyph styles, geometry, and page evidence
`extract.image_mode`	`none`	`embedded`, `render_pages`, or `both` requests image payloads

The result always carries metadata, total_pages, and diagnostics, so page failures and the page cap are visible whatever content was selected. Requested image bytes appear once in the result’s images array as data_base64, independently of output.basic. Basic evidence is the per-page material only (raw_text, glyphs, lines, image metadata); it repeats nothing the top level states. The Rust SDK and internal worker keep the full typed BasicDocument, including image bytes.

For evidence without organization, use one invocation so validation sees the complete configuration:

afpdf extract article.pdf --set output.basic=true \
  --set output.article=false --set output.text=false \
  --set extract.processing=null

At least one content field or image mode must be enabled. Article and text output require non-null extract.processing. Disabling an output field does not itself disable extraction or organization; these are separate decisions.

Organization options

These keys live under extract.processing and default to true:

Key	When disabled
`remove_page_furniture`	Keep page numbers and repeated running headers/footers
`merge_paragraphs`	Keep visual lines separate and disable cross-page joins
`merge_across_pages`	Keep paragraph fragments separate at page boundaries
`drop_clipped_text`	Include text outside recognized clipping bounds
`place_images`	Omit figure blocks from reading order; retain image metadata

extract.processing.expected_language defaults to auto. Set chinese only when the Chinese text-layer heuristic is appropriate; it is not an OCR option. See design.md for the evidence and limits of these heuristics.

Execution and native dependencies

execution.isolated defaults to true. The current executable starts its own internal worker for each document.

The PDFium library is chosen by execution.engine: library_path names a shared library file explicitly; otherwise the library in install_dir is used when present, and the platform’s own search for pdfium otherwise. An empty install_dir means the per-user data directory (afpdf/engine under it).

# Fetch the pinned PDFium build, verify it, and probe it.
afpdf engine install
# Which library would load, does it load, and what does this platform enforce.
afpdf engine status
# Use a library you provide instead.
afpdf extract article.pdf --set execution.engine.library_path=/opt/pdfium/libpdfium.so

Default limits are 500 pages, 120 MiB input (also the maximum), 40 million pixels per image, 300000 ms per document, and 256 MiB worker output. The worker address-space limit is enforced on Linux only, so it defaults to 2 GiB there and to zero (no limit) elsewhere; setting it nonzero on another platform fails every extraction explicitly. Use afpdf config show to discover the full typed configuration, including page range, image format, rendering resolution, and limits.

execution.isolated=false selects in-process extraction, which has no hard wall-clock timeout or native crash containment. A child process contains crashes; it is not a filesystem or network sandbox.

--stdout-file and --stderr-file redirect streams on Unix only. On Windows the invocation fails before anything runs with output_redirect_unsupported; use --output-to or the shell’s own redirection there.

File safety and extension

Configuration files are capped at 1 MiB. Edits validate the full resulting configuration before committing; an invalid first edit creates no file or directory, and an invalid later edit leaves the existing file unchanged. Atomic saves prevent partial replacement, but do not merge concurrent edits.

To add a setting, extend the appropriate typed model, its defaults and validation. AFDATA handles dot paths, coercion, help, and document edits; no per-setting CLI flag or configuration dispatcher is needed. SDK callers pass typed options explicitly and do not load the CLI configuration file.