pdfstamp

pdfstamp is a terminal-only PDF stamp-region picker. It renders a coarse, content-aware page preview directly in the terminal and lets you place text and image stamps with the keyboard, save the layout as a JSON plan, and burn the stamps into an output PDF.

It does coarse placement, not pixel-perfect editing. Zoom in for finer control over stamps, initials, signatures, dates, and labels.

Build

pdfstamp uses MuPDF (via go-fitz) for rendering, which requires cgo. go-fitz bundles musl-built MuPDF static libraries (no system PDF library is needed), and the build links fully static: the one binary has no libc dependency and runs on both glibc and musl machines.

On Alpine:

apk add build-base go
make build

On Debian, install the musl toolchain and select it explicitly:

apt install build-essential musl-tools
make build CC=musl-gcc

There is no native Windows build; on Windows, run the same static binary under WSL.

Usage

pdfstamp pick INPUT.pdf [-o PLAN.json]   place stamps; write the plan
pdfstamp apply PLAN.json OUTPUT.pdf      burn a plan into an output PDF
pdfstamp INPUT.pdf OUTPUT.pdf            pick then apply in one step

With no -o, pick writes the plan to stdout. apply reads the plan from stdin when the path is -, so the two steps compose as a pipe:

pdfstamp pick INPUT.pdf | pdfstamp apply - OUTPUT.pdf

The picker draws to /dev/tty, so stdout carries only the plan. apply reads the source PDF path from the plan's "input" field. A sample document ships with the repo; try:

pdfstamp pick example.pdf -o plan.json
pdfstamp apply plan.json stamped.pdf

Controls

The picker is modal on selection: with no stamp selected, h/j/k/l move the cursor; with a stamp selected (tab), they move the stamp.

n / p      next / previous page
g          go to page
h j k l    move cursor (or selected stamp)
arrows     move (same as h j k l)
H J K L    resize selected stamp
space      start / finish a rectangle, then add a stamp in it
a          add a stamp at the cursor (or edit the selected one)
d          delete the selected stamp
P          set the selected stamp's pages (e.g. 1,3-5 or all)
o          set the selected stamp's opacity (0-1)
tab        cycle stamp selection (and back to cursor mode)
+ / -      zoom in / out
enter      save the plan (pick), or apply and quit (one-step)
?          toggle help
q          quit

A truecolor terminal (COLORTERM=truecolor) gets a colored half-block preview; otherwise a grayscale ASCII preview is used. tmux and screen usually strip COLORTERM; set it inside the multiplexer to keep the colored preview.

Plan format

The plan is plain JSON. Coordinates are PDF points with a bottom-left origin. Pages are 1-based. Text uses Helvetica, sized to fit the rectangle (no per-stamp font/size/color). Only printable ASCII is supported, as no font is embedded; plans with other characters are rejected. Images (PNG or JPEG) are scaled to fit the rectangle while preserving aspect ratio, anchored at the bottom-left corner.

pick writes absolute paths so a saved plan applies from any directory. In a hand-written plan, relative "input" and "src" paths are resolved relative to the plan file's directory (or the working directory when the plan is read from stdin).

{
  "version": 2,
  "input": "input.pdf",
  "stamps": [
    { "id": "stamp-1", "type": "text", "content": "APPROVED",
      "pages": [1], "rect": { "x": 420, "y": 610, "w": 120, "h": 42 },
      "opacity": 0.8 },
    { "id": "stamp-2", "type": "image", "src": "sig.png",
      "pages": [1, 3], "rect": { "x": 100, "y": 90, "w": 80, "h": 40 },
      "opacity": 1.0 }
  ]
}

How it works

pick rasterizes each page with MuPDF and draws it as Unicode half-blocks, one character per two vertical pixels, mapping terminal cells to PDF points.

apply builds an in-memory overlay PDF with one page per source page, drawing each stamp at its exact point coordinates (text via a base-14 Helvetica content stream, images as RGB XObjects with a soft-mask for transparency). pdfcpu then overlays that PDF onto the source 1:1 (multi-stamp, centered, scale 1, no rotation) and validates the result. Because the overlay pages share the source MediaBoxes, the overlay is an identity transform. On pages with /Rotate, the overlay uses the viewed page size and pdfcpu counter-rotates it, so stamps land where the picker showed them.

Debugging

The overlay content streams are uncompressed and human-readable; dump the overlay or output with a viewer or strings to inspect the drawing operators (cm, Tj, Do). Run the integration test, which applies a known plan and asserts that stamps land in the expected pixel regions:

make test

On Debian, use the same musl compiler override as the build:

make test CC=musl-gcc

If stamps appear rotated or offset, check the watermark fields set in apply.go: pdfcpu defaults to a diagonal placement, so Rotation 0 and NoDiagonal must both be set to get a straight 1:1 overlay.

Exit status

0 on success, 1 on runtime errors, 2 on usage errors. The picker exits 130 on SIGINT and 143 on SIGTERM, after restoring the terminal.

Limitations

apply refuses, rather than silently misplacing stamps, on pages it cannot map 1:1: pages whose MediaBox/CropBox origin is not at (0,0). Text stamps are printable ASCII only (no embedded font). Each stamp image is capped at 50 megapixels, with a 100-megapixel total across distinct images.

License

pdfstamp links MuPDF (AGPL-3.0). Distributing the binary therefore puts it under the AGPL-3.0 unless you hold a commercial MuPDF license. pdfcpu is Apache-2.0.