flpdf-cli 0.9.0

Command-line tools for flpdf, mirroring qpdf inspection and rewrite subcommands.
flpdf-cli-0.9.0 is not a library.

flpdf

A Pure Rust PDF toolkit modeled on the qpdf workflow. flpdf aims for writer-level parity with qpdf — its outputs are continuously compared against qpdf reference outputs through a golden matrix (see docs/qpdf-compat.md).

Workspace layout

This repository is a Cargo workspace with two crates:

Crate Path Purpose
flpdf crates/flpdf Core PDF reader / writer library.
flpdf-cli crates/flpdf-cli CLI (flpdf binary) that wraps the library.

Both crates are licensed under MIT OR Apache-2.0.

Building

cargo build --workspace
cargo test  --workspace

The default build is Pure Rust; flpdf depends on flate2 without pinning a backend, so cargo build resolves to flate2's default (miniz_oxide).

Choosing a DEFLATE backend (downstream consumers)

flpdf does not re-export flate2's backend features (zlib-rs, zlib, zlib-ng, …) as its own features. A downstream crate that wants a specific backend adds flate2 as a direct dependency and enables the feature there; Cargo's feature unification applies it to flpdf's copy of flate2 too. This follows the pattern that krilla PR #390 settled on — keeping the backend choice with the consumer avoids forcing a single implementation on every downstream build.

# Pure Rust, faster than miniz_oxide, WASM-friendly.
[dependencies]
flpdf  = "..."
flate2 = { version = "1", features = ["zlib-rs"] }
# System libz — matches qpdf's compress2() byte-for-byte.
[dependencies]
flpdf  = "..."
flate2 = { version = "1", features = ["zlib"] }

[!TIP] Because flate2 here is a Cargo-feature knob rather than a crate you actually use, tools like cargo-machete and cargo-udeps will flag it as an unused dependency. Ignore it in your Cargo.toml:

[package.metadata.cargo-machete]
ignored = ["flate2"]

[package.metadata.cargo-udeps.ignore]
normal = ["flate2"]

qpdf-zlib-compat (internal parity feature)

The optional qpdf-zlib-compat feature on the flpdf crate pins flate2's backend to classic libz (via libz-sys) for flpdf's own bytes-identical test suite. It is used by the parity CI job only and is not intended for production consumers — pick a backend via the pattern above instead.

cargo test -p flpdf --features qpdf-zlib-compat

CLI usage

cargo build --release -p flpdf-cli
./target/release/flpdf --help

Common subcommands (flpdf <subcommand> --help for full options):

flpdf check input.pdf                       # validate structure / report diagnostics
flpdf pages input.pdf                       # show page structure
flpdf qdf      input.pdf  out.qdf           # qdf-style flat dump
flpdf rewrite  input.pdf  out.pdf           # fresh full rewrite
flpdf rewrite --linearize    in.pdf out.pdf # produce a linearized PDF
flpdf zlib-flate -compress < in.bin > out.z # raw zlib compression (stdin/stdout)

The zlib-flate subcommand also ships as a standalone zlib-flate binary alias. It accepts qpdf's -uncompress, -compress, and -compress=n forms.

Encrypted inputs are supported via --password, --password-file, and --password-mode {auto,bytes,hex-bytes,unicode} (the unicode mode validates UTF-8 and preserves the supplied bytes for V=5 R=5/R=6 handlers, matching qpdf 11.9.0). RC4-backed handlers and revision 5 encryption are gated behind --allow-weak-crypto.

--static-id, --min-version, --force-version, and the qpdf compatibility flags (--compress-streams, --linearize-pass1) are accepted on rewrite to keep qtest-style command lines parsing cleanly.

Library usage

use std::fs::File;
use std::io::BufReader;
use flpdf::{pages, write_pdf, Pdf};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = BufReader::new(File::open("input.pdf")?);
    let mut pdf = Pdf::open(file)?;

    for object_ref in pages::page_refs(&mut pdf)? {
        println!("page: {object_ref}");
    }

    let mut out = File::create("output.pdf")?;
    write_pdf(&mut pdf, &mut out)?;
    Ok(())
}

The crate is organized as a few small layers:

  • Pdf — parsed-but-lazy document handle (Pdf::open reads the trailer and cross-reference table; ObjectHandle::try_* accessors resolve objects on demand).
  • Object, Dictionary, Stream, ObjectRef — the data model.
  • pages, outline_object_helper — read-only traversal helpers that mirror qpdf --show-pages and --json-key=outlines.
  • write_pdf / write_qdf — fresh full rewrite and qdf-style flat dump.
  • job::QPDFJob::check — qpdf-compatible document validation and warning completion for CLI and library job consumers.

Errors flow through the unified Error enum and the crate-level Result alias. See the rustdoc on crates/flpdf/src/lib.rs for the full API.

Examples

Runnable examples live in crates/flpdf/examples. Each one is a small, self-contained program; run any of them with:

cargo run --example <name> -p flpdf
Example Description
inspect Inspect and dump a PDF's basic structure end to end.
extract_page Extract a single page (0-based) into a new minimal PDF.
extract_pages Extract a non-contiguous selection (pages 1, 3, 5) into a new file.
extract_first_5_pages Extract the first 5 pages of a document into a new file.
list_form_fields List every interactive form field with its type and value.
walk_outline Walk the document outline (bookmarks) as an indented tree.
pull_attachments Pull every embedded attachment out of a document to disk.
reorder_pages Reorder a document's pages (here: reverse them) and write the result.
merge_pdfs Merge two PDFs, preserving fonts shared between the merged-in pages.
splice_pages Splice pages from one document into another at a given index.

qpdf compatibility

flpdf's writer-level outputs are compared against qpdf in two places:

  • Golden matrix — tests/golden/compat-matrix.md, one row per (fixture, flag) tuple and one column per comparator strategy. Regenerated with BLESS=1 cargo test -p flpdf-cli --test compat_matrix_baseline.
  • Decisions registry — docs/qpdf-compat-decisions.md records every deliberate divergence point so contributors can tell intentional gaps from incidental ones.

The full workflow lives in docs/qpdf-compat.md. When your change re-blesses the matrix or the static-ID baseline, check the PR template's "Compat matrix" section.

Contributing

See CONTRIBUTING.md for the contributor guide and AGENTS.md / CLAUDE.md for AI-agent conventions. Issue tracking uses beads; start with bd ready to see available work.

License

Licensed under either of

  • Apache License, Version 2.0
  • MIT License

at your option.