Command-line tool

gopdfrab on the command line

The same verification and conversion engine as the library, as a single static binary. No Go, no JVM, no runtime — it drops straight into scripts and CI.

Install

The CLI ships in the same module, under cmd/gopdfrab.

terminal

go install github.com/voidrab/gopdfrab/cmd/gopdfrab@latest

Usage

Two subcommands do the work. verify accepts any mix of files and directories, walking directories recursively; convert rewrites a single input.

gopdfrab help

gopdfrab -- verify and convert PDFs for PDF/A-1b conformance

usage:
  gopdfrab verify  [flags] <path-or-dir>...   verify conformance (dirs walked recursively)
  gopdfrab convert [flags] <input> [output]   rewrite a PDF towards conformance
  gopdfrab version                            print the version
  gopdfrab help                               show this help

exit codes: 0 conformant, 1 non-conformant, 2 error

Run "gopdfrab verify -h" or "gopdfrab convert -h" for command flags.

Exit codes

Conformance is reported through the exit status, so a pipeline can gate on it without parsing any output.

exit 0

Conformant — every file passed.

exit 1

Non-conformant — at least one file failed.

exit 2

Error — usage, open, or I/O failure.

Examples

terminal

gopdfrab verify docs/                     # verify every PDF under a directory
gopdfrab verify --json report.pdf         # machine-readable output
gopdfrab convert in.pdf out.pdf           # rewrite towards PDF/A-1b
gopdfrab convert --dpi 300 in.pdf         # tune the raster fallback
gopdfrab verify --max-decoded-mb 64 x.pdf # cap decoded stream output at 64 MB

Flags

Both subcommands accept these:

Flag	Value	Description
--profile	pdfa1b \| legacy1b \| pdf	Conformance profile. Default pdfa1b (veraPDF-aligned); legacy1b is the strict Isartor-derived profile; pdf runs the generic ISO 32000 object-model checks.
--password	string	Password for an encrypted input. Empty-password files are decrypted automatically.
--max-decoded-mb	int	Cap a single stream's decoded output, in MB. 0 uses the default of 256.
--max-resident-mb	int	Cap a document's rebuildable caches, in MB. 0 uses the default of 64.
--json	bool	Emit machine-readable JSON instead of the human-readable report.

convert adds:

Flag	Value	Description
--dpi	int	Raster fallback resolution. 0 uses the default of 150.
--max-iterations	int	Bound on the verify/fix loop. 0 uses the default of 4.
-o	path	Output path. Defaults to the input with a .pdfa.pdf suffix, or .fixed.pdf for the pdf profile. A positional output argument works too.

The pdf profile

--profile pdf skips PDF/A entirely and runs the generic ISO 32000 object-model checks derived from the Arlington PDF Model — it answers "is this even valid PDF?". See the object-model section in the docs.

JSON output

--json swaps the human-readable report for the same stable JSON shape the library marshals, so results can be diffed, filtered, or archived.

terminal

# verify --json emits an array of {path, error?, result?}
gopdfrab verify --json docs/ | jq -r '.[] | select(.result.valid == false) | .path'

report.json

In CI

Because the binary is static and starts in single-digit milliseconds, running it on every commit costs almost nothing. Gate a build on conformance by leaning on the exit code.

check-pdfa.sh

#!/usr/bin/env bash
# Fail the build when any PDF under docs/ is not PDF/A-1b conformant.
set -euo pipefail

if gopdfrab verify docs/; then
  echo "all documents are conformant"
else
  status=$?
  if [ "$status" -eq 1 ]; then
    echo "::error::one or more documents are not PDF/A-1b conformant"
  else
    echo "::error::gopdfrab failed to run"
  fi
  exit "$status"
fi