pdftract/docs/user-docs/src/cli-reference.md

CLI Reference

This page is auto-generated from the clap command tree. Run cargo run --bin gen-cli-reference to regenerate.

Command-Line Help for pdftract

This document contains the help content for the pdftract command-line program.

Command Overview:

• pdftract↴
• pdftract list-diagnostics↴
• pdftract explain-diagnostic↴
• pdftract compare↴
• pdftract conformance↴
• pdftract sdk↴
• pdftract sdk codegen↴
• pdftract sdk validate↴
• pdftract extract↴
• pdftract classify↴
• pdftract inspect↴
• pdftract verify-receipt↴
• pdftract hash↴
• pdftract cache↴
• pdftract cache stats↴
• pdftract cache clear↴
• pdftract cache purge↴
• pdftract profiles↴
• pdftract profiles list↴
• pdftract profiles show↴
• pdftract profiles export↴
• pdftract profiles install↴
• pdftract profiles validate↴
• pdftract serve↴
• pdftract mcp↴
• pdftract validate↴
• pdftract migrate-schema↴
• pdftract doctor↴

pdftract

pdftract CLI - PDF extraction and conformance testing

Usage: pdftract <COMMAND>

Subcommands:

• list-diagnostics — List all diagnostic codes with their metadata
• explain-diagnostic — Explain a specific diagnostic code in detail
• compare — Compare actual results against expected values with tolerances (for conformance testing)
• conformance — Run SDK conformance test suite
• sdk — SDK code generation commands
• extract — Extract text and structure from a PDF file
• classify — Classify document type (runs metadata + signal extraction, not full text extraction)
• inspect — Inspect a PDF file in a local web browser with debugging overlays
• verify-receipt — Verify a receipt against a PDF file
• hash — Compute the PDF structural fingerprint (hash)
• cache — Manage the extraction cache
• profiles — Manage document type profiles
• serve — Start the HTTP server for extraction
• mcp — Start the MCP (Model Context Protocol) server
• validate — Validate a JSON file against the pdftract schema
• migrate-schema — Migrate JSON output between schema versions
• doctor — Check environment health and dependencies

pdftract list-diagnostics

List all diagnostic codes with their metadata

Usage: pdftract list-diagnostics

pdftract explain-diagnostic

Explain a specific diagnostic code in detail

Usage: pdftract explain-diagnostic <CODE>

Arguments:

• <CODE> — Diagnostic code to explain (e.g., STRUCT_MISSING_KEY, STREAM_BOMB)

pdftract compare

Compare actual results against expected values with tolerances (for conformance testing)

Usage: pdftract compare [OPTIONS] <ACTUAL> <EXPECTED>

Arguments:

• <ACTUAL> — Path to the actual results JSON
• <EXPECTED> — Path to the expected results JSON

Options:

• -t, --tolerances <TOLERANCES> — Path to the tolerances JSON (optional)

• -f, --format <FORMAT> — Output format (text, json)

  Default value: text

pdftract conformance

Run SDK conformance test suite

Usage: pdftract conformance [OPTIONS]

Options:

• -s, --suite <SUITE> — Path to the conformance suite JSON

  Default value: tests/sdk-conformance/cases.json

• -k, --sdk <SDK> — SDK name

  Default value: pdftract

• -v, --version <VERSION> — SDK version

  Default value: 0.1.0

• -o, --output <OUTPUT> — Output report path

  Default value: conformance-report.json

pdftract sdk

SDK code generation commands

Usage: pdftract sdk <COMMAND>

Subcommands:

• codegen — Generate SDK skeleton from templates
• validate — Validate existing SDK against current generator output

pdftract sdk codegen

Generate SDK skeleton from templates

Usage: pdftract sdk codegen --lang <LANG> --out <OUT>

Options:

• -l, --lang <LANG> — Target language

  Possible values: python, rust, node, go, java, dotnet, ruby, php, swift

• -o, --out <OUT> — Output directory

• -v, --version <VERSION> — Version string (defaults to current pdftract version)

  Default value: 0.1.0

pdftract sdk validate

Validate existing SDK against current generator output

Usage: pdftract sdk validate --lang <LANG> --sdk-dir <SDK_DIR>

Options:

• -l, --lang <LANG> — Target language

  Possible values: python, rust, node, go, java, dotnet, ruby, php, swift

• -s, --sdk-dir <SDK_DIR> — Path to existing SDK directory

pdftract extract

Extract text and structure from a PDF file

Usage: pdftract extract [OPTIONS] <INPUT>

Arguments:

• <INPUT> — Path to the PDF file (use '-' for stdin)

Options:

• --password-stdin — Read password from stdin (one line, terminated by newline)

• --password <PASSWORD> — PDF password (INSECURE: rejected unless PDFTRACT_INSECURE_CLI_PASSWORD=1)

• --header <HEADER:VALUE> — Custom HTTP headers for remote sources (repeatable; format: HEADER:VALUE)

• --pages <RANGE> — Page range to extract (1-based, comma-separated: 1-5,7,12-)

• --json <PATH> — Output JSON to PATH (use '-' for stdout)

• --md <PATH> — Output Markdown to PATH (use '-' for stdout)

• --text <PATH> — Output plain text to PATH (use '-' for stdout)

• --ndjson — Output NDJSON to stdout (mutually exclusive with other formats)

• --format <FORMATS> — Output formats (comma-separated: json,markdown,text,ndjson)

• -o, --output <BASE> — Base path for auto-named outputs (used with --format)

• --receipts <MODE> — Receipt mode: off (default), lite, or svg

  Default value: off

  Possible values: off, lite, svg

• --ocr — Enable OCR for scanned pages (requires 'ocr' feature)

• --ocr-language <OCR_LANGUAGE> — OCR language codes (comma-separated, e.g., 'eng,fra,deu')

• --cache-dir <DIR> — Enable cache at this directory (creates if absent)

• --cache-size <SIZE> — Set cache size limit (default 1 GiB; accepts KiB, MiB, GiB suffixes)

  Default value: 1 GiB

• --no-cache — Disable cache for this extraction (even if --cache-dir is set)

• --md-anchors — Emit HTML comment anchors before each block in Markdown output

• --md-no-page-breaks — Suppress page-break horizontal rules between pages

• --auto — Auto-detect document type and apply appropriate profile

• --profile <NAME|PATH> — Force-apply a specific profile (by name or YAML file path)

• --include-headers — Include header blocks in output

• --include-footers — Include footer blocks in output

• --include-headers-footers — Include both header and footer blocks in output

• --include-invisible-text — Include invisible text spans in output (rendering_mode == 3)

• --include-hidden-layers — Include hidden-layer text spans in output (OCG-controlled)

• --include-watermarks — Include watermark blocks in output (no-op until Phase 7)

pdftract classify

Classify document type (runs metadata + signal extraction, not full text extraction)

Usage: pdftract classify [OPTIONS] <INPUT>

Arguments:

• <INPUT> — Path to the PDF file

Options:

• --password-stdin — Read password from stdin (one line, terminated by newline)

• --password <PASSWORD> — PDF password (INSECURE: rejected unless PDFTRACT_INSECURE_CLI_PASSWORD=1)

• --profiles <DIR> — Directory containing custom profile YAML files

• --pretty — Pretty-print JSON output

• --top-k <TOP_K> — Number of top reasons to include (default: all)

  Default value: 0

• --exit-on-unknown — Exit with code 1 if document type is unknown

pdftract inspect

Inspect a PDF file in a local web browser with debugging overlays

Usage: pdftract inspect [OPTIONS] <FILE>

Arguments:

• <FILE> — Path to the PDF file to inspect

Options:

• -p, --port <PORT> — Port to bind the inspector server (default: 7676)

  Default value: 7676

• -b, --bind <BIND> — Bind address for the inspector server (default: 127.0.0.1)

  Binding to a non-loopback address requires --auth-token for security.

  Default value: 127.0.0.1

• --auth-token <AUTH_TOKEN> — Authentication token for non-loopback binds

  Required when --bind is not a loopback address (127.0.0.1 or ::1).

• --no-open — Suppress automatic browser launch

  Useful for CI environments or when you want to manually open the browser.

• --compare <FILE> — Optional second PDF file for comparative debugging

  When provided, the inspector shows side-by-side comparison.

• --audit-log <FILE> — Write per-request audit log to FILE (NDJSON; use "-" for stdout, "/dev/stderr" for stderr)

  Rotation: pdftract does NOT rotate logs; configure logrotate on the audit-log file. When FILE is "-", rotation is the responsibility of the supervisor (e.g., journald).

pdftract verify-receipt

Verify a receipt against a PDF file

Usage: pdftract verify-receipt [OPTIONS] <FILE.pdf> <RECEIPT.json>

Arguments:

• <FILE.pdf> — Path to the PDF file to verify against
• <RECEIPT.json> — Path to the receipt JSON file, or "-" for stdin

Options:

• --stdin — Read receipt from stdin (alternative to "-")
• --inline <INLINE> — Receipt JSON as inline string (alternative to file path)
• --json — Output machine-readable JSON result
• --quiet — Suppress human-readable output (exit code only)
• --password <PASSWORD> — PDF password (INSECURE: rejected unless PDFTRACT_INSECURE_CLI_PASSWORD=1)
• --password-stdin — Read password from stdin (one line, terminated by newline)

pdftract hash

Compute the PDF structural fingerprint (hash)

Usage: pdftract hash [OPTIONS] <INPUT>

Arguments:

• <INPUT> — Path to the PDF file or URL

Options:

• --password <PASSWORD> — PDF password (INSECURE: rejected unless PDFTRACT_INSECURE_CLI_PASSWORD=1)
• --header <HEADER:VALUE> — Custom HTTP headers for remote sources (repeatable; format: HEADER:VALUE)

pdftract cache

Manage the extraction cache

Usage: pdftract cache <COMMAND>

Subcommands:

• stats — Show cache statistics
• clear — Clear all cache entries (preserves index.json and sentinel)
• purge — Purge old cache entries

pdftract cache stats

Show cache statistics

Usage: pdftract cache stats [OPTIONS] <DIR>

Arguments:

• <DIR> — Path to the cache directory

Options:

• --json — Output in JSON format

pdftract cache clear

Clear all cache entries (preserves index.json and sentinel)

Usage: pdftract cache clear [OPTIONS] <DIR>

Arguments:

• <DIR> — Path to the cache directory

Options:

• -y, --yes — Skip confirmation prompt

pdftract cache purge

Purge old cache entries

Usage: pdftract cache purge [OPTIONS] <DIR>

Arguments:

• <DIR> — Path to the cache directory

Options:

• --older-than <DURATION> — Delete entries older than this duration (e.g., "30d", "7d", "1h")
• --version <CONSTRAINT> — Delete entries matching this version constraint (e.g., "<1.0.0")

pdftract profiles

Manage document type profiles

Usage: pdftract profiles <COMMAND>

Subcommands:

• list — List all available profiles
• show — Show a profile's YAML content
• export — Export a built-in profile to stdout
• install — Install a profile to the user config directory
• validate — Validate a profile file

pdftract profiles list

List all available profiles

Usage: pdftract profiles list

pdftract profiles show

Show a profile's YAML content

Usage: pdftract profiles show <NAME_OR_PATH>

Arguments:

• <NAME_OR_PATH> — Profile name or path to YAML file

pdftract profiles export

Export a built-in profile to stdout

Usage: pdftract profiles export <NAME>

Arguments:

• <NAME> — Name of the built-in profile to export

pdftract profiles install

Install a profile to the user config directory

Usage: pdftract profiles install <PATH>

Arguments:

• <PATH> — Path to the profile YAML file to install

pdftract profiles validate

Validate a profile file

Usage: pdftract profiles validate <PATH>

Arguments:

• <PATH> — Path to the profile YAML file to validate

pdftract serve

Start the HTTP server for extraction

Security Model

pdftract serve has no built-in authentication. Deploy behind a reverse proxy (nginx, Traefik, Caddy) for production use. The server accepts PDFs via multipart upload only; no endpoint accepts file paths from server filesystem.

Concurrency

The server uses a two-level concurrency architecture:

• tokio: Per-request concurrency via the async executor. Each HTTP request is handled asynchronously on tokio's multi-threaded runtime. - rayon: Per-document parallelism within each extraction. PDF pages are processed in parallel using rayon's work-stealing thread pool.

The bridge between async (tokio) and sync (rayon) is tokio::task::spawn_blocking. Each POST handler wraps the synchronous extraction call in spawn_blocking, which runs the work on tokio's blocking thread pool (separate from the async reactor).

This design ensures: - The async reactor is never blocked by extraction work - Multiple PDFs can be extracted concurrently (one per request) - Within each PDF, pages are processed in parallel (rayon) - Thread pools are sized appropriately (tokio: 512 blocking threads; rayon: num_cpus)

Endpoints

• POST /extract - Extract PDF and return JSON with metadata - POST /extract/text - Extract PDF and return plain text - POST /extract/stream - Extract PDF and return streaming NDJSON - GET /health - Health check (responds within 100ms even during concurrent extractions)

Cache

Cache is optional. When enabled, extracted results are stored on disk and reused for identical PDFs. Cache status is reported via the X-Pdftract-Cache response header.

Usage: pdftract serve [OPTIONS]

Options:

• -b, --bind <BIND> — Bind address (e.g., "127.0.0.1:8080", "[::1]:9000", "0.0.0.0:3000")

  Default value: 127.0.0.1:8080

• --cache-dir <DIR> — Enable cache at this directory

• --cache-size <SIZE> — Set cache size limit (default 1 GiB; accepts KiB, MiB, GiB suffixes)

  Default value: 1 GiB

• --no-cache — Disable cache

• --max-upload-mb <MAX_UPLOAD_MB> — Maximum request body size in MB (default: 256, max: 4096)

  Default value: 256

• --max-decompress-gb <GB> — Maximum decompression size in GB (default: 1, overrides per-request max_decompress_gb)

  Default value: 1

• --audit-log <FILE> — Write per-request audit log to FILE (NDJSON; use "-" for stdout, "/dev/stderr" for stderr)

  Rotation: pdftract does NOT rotate logs; configure logrotate on the audit-log file. When FILE is "-", rotation is the responsibility of the supervisor (e.g., journald).

• --trust-forwarded-for — Trust X-Forwarded-For header for client IP detection (DANGER: enables IP spoofing if not behind a trusted proxy)

• --profile-dir <DIR> — Directory containing custom profile YAML files (repeatable)

• --profile-hot-reload — Enable hot-reload for profiles (re-read directory on every request)

pdftract mcp

Start the MCP (Model Context Protocol) server

Per ADR-006: stdio and HTTP transports are mutually exclusive because they have opposite stdout discipline (stdio: JSON-RPC sink; HTTP: log channel). Exactly one transport must be selected per invocation.

Usage: pdftract mcp [OPTIONS]

Options:

• --stdio — Use stdio transport (for Claude Desktop, Claude Code, Continue, Cursor)

  This is the default transport mode if neither --stdio nor --bind is specified.

• -b, --bind <ADDR> — Bind address for the MCP server (e.g., "127.0.0.1:8080", "[::1]:9000", "0.0.0.0:3000")

  Enables HTTP+SSE transport mode. Mutually exclusive with --stdio.

• --auth-token-file <AUTH_TOKEN_FILE> — Path to a file containing the bearer token (RECOMMENDED)

• --auth-token <AUTH_TOKEN> — Bearer token for authentication (INSECURE: rejected unless PDFTRACT_INSECURE_CLI_TOKEN=1)

• --max-upload-mb <MAX_UPLOAD_MB> — Maximum request body size in MB (default: 256)

  Default value: 256

• --root <DIR> — Root directory for local filesystem access (enforces path-traversal protection)

  When set, all local-path tool arguments are resolved relative to DIR and any path that escapes DIR is rejected with JSON-RPC error code -32602. HTTPS URLs are not affected by this flag. Without --root, the server runs in trust-the-caller mode (no path-check applied).

• --audit-log <FILE> — Write per-request audit log to FILE (NDJSON; use "-" for stdout, "/dev/stderr" for stderr)

  Rotation: pdftract does NOT rotate logs; configure logrotate on the audit-log file. When FILE is "-", rotation is the responsibility of the supervisor (e.g., journald).

pdftract validate

Validate a JSON file against the pdftract schema

Usage: pdftract validate [OPTIONS] <FILE>

Arguments:

• <FILE> — Path to the JSON file to validate (use '-' for stdin)

Options:

• -s, --schema <PATH> — Path to a custom schema file (default: bundled v1.0 schema)
• -q, --quiet — Quiet mode - suppress error output (only exit code matters)

pdftract migrate-schema

Migrate JSON output between schema versions

Usage: pdftract migrate-schema [OPTIONS] --from <FROM> --to <TO> [INPUT]

Arguments:

• <INPUT> — Input JSON file (use '-' for stdin)

  Default value: -

Options:

• --from <FROM> — Source schema version (e.g., "1.0", "1.1")

• --to <TO> — Target schema version (e.g., "1.0", "1.1")

• -o, --output <OUTPUT> — Output JSON file (use '-' for stdout)

  Default value: -

• -p, --pretty — Pretty-print output JSON

pdftract doctor

Check environment health and dependencies

Exit code policy: exits 0 if no checks FAIL (WARN does not affect exit code); exits 1 if any check FAILs; exits 2 on argument parse errors.

Usage: pdftract doctor [OPTIONS]

Options:

• --features — Print compiled features and exit

• --json — Output results as JSON

• --no-color — Disable colored output

• --exit-on-fail — Explicit form of the default policy (exit 1 if any check FAILs).

  This flag is the default behavior and is provided for CI script readability. WARN does not affect exit code regardless of this flag.

• --profile-dir <DIR> — Verify the profile search path includes DIR

• --cache-dir <DIR> — Verify DIR is writable and has sufficient space

• --lang <LANG> — Requested OCR languages (default: eng)

---

This document was generated automatically by clap-markdown.

Hand-Curated Content

Note: Any content added after this marker will be preserved when the CLI reference is regenerated. This section is for additional context that doesn't fit in the auto-generated sections.

Common Patterns

Basic Extraction

pdftract extract document.pdf

JSON Output

pdftract extract --json output.json document.pdf

Markdown with Anchors

pdftract extract --md-anchors --md output.md document.pdf

Exit Codes

• 0: Success
• 1: General error (extraction failed, file not found, etc.)
• 2: Usage error (invalid arguments, conflicting flags)
• 3: Decryption error (wrong or missing password)