Passwords and Global Flags

Passwords and Global Flags

Global flags

Flag	Effect
-c, --conf PATH	use a specific config root; disable = stateless mode
--force	allow overwriting files and other destructive operations
-o, --offline	disable all HTTP traffic
-q, --quiet	suppress output
-v, --verbose	verbosity; repeat for more (-v, -vv)
--opw / --upw	owner / user password for encrypted input

Passwords

Most PDFs are protected with a user password (open document) and/or an owner password (change permissions). Supply them via flags:

pdfcpu2 validate --upw "secret" in.pdf
pdfcpu2 decrypt --upw "secret" in.pdf out.pdf
pdfcpu2 encrypt --opw "owner" --upw "user" in.pdf out.pdf

Password files

Every literal --upw / --opw flag has a --upw-file / --opw-file counterpart — for CI, containers and secret managers:

pdfcpu2 decrypt --upw-file /run/secrets/upw in.pdf out.pdf

Rules:

• One trailing line ending (LF or CRLF) is allowed and ignored; anything else (spaces, extra newlines) is part of the password.
• An empty file supplies an empty password.
• Supply a password either directly or via file, never both.
• Password files need a real filename — stdin is not supported for them.

stdin / stdout with -

Wherever a command documents "use - to read from stdin" or "write to stdout", - is the marker. This makes pdfcpu2 pipe-friendly:

# fetch from object storage, process, push back — no temp files
aws s3 cp s3://bucket/report.pdf - \
  | pdfcpu2 watermark add "DRAFT" "diag:1, op:.25" - - \
  | aws s3 cp - s3://bucket/report-draft.pdf

cat in.pdf | pdfcpu2 extract -m text - -

Notable exceptions: ocr requires real files (no stdin), and password files must be named files.

Exit codes and diagnostics

Commands fail with a non-zero exit status and a diagnostic message. Add -v to trace parsing; -vv for full dumps. --force is required whenever an output file already exists and would be overwritten.