← All guides

The pipeline: one line that does five things

A messy scan needs its junk pages dropped, its sideways pages turned, its paper whitened, a text layer added, and the whole thing squeezed under an upload cap. That used to be five commands and four temp files. It is one line now, shaped like the one little language everyone already knows: the Unix pipe.

pip install "pdfblah[app]"

pdfblah do 'tidy | rotate auto | clean | ocr | shrink 200kb' scan.pdf -o clean.pdf

The whole grammar

Steps joined by |. Each step is a pdfblah command in the words the CLI already speaks; key=value sets its flags, a bare word is a bare flag, and explicit --flags work too. Any command that turns a PDF into a PDF is a valid step (pdfblah verbs marks them with a |). That's all of it.

# the same pipeline, three ways to say the pieces
pdfblah do 'redact find="Account 12345" | watermark CONFIDENTIAL | sanitize' in.pdf -o out.pdf
pdfblah do 'compress target=200kb grayscale' in.pdf -o out.pdf
pdfblah do 'pages --drop 1 | bates prefix=EXH- start=auto' evidence/ -o stamped/

A little sugar, kept scarce

A few things read better as words, so they are words:

pdfblah do 'dark' book.pdf -o book-dark.pdf        # dark, sepia, ink navy
pdfblah do 'straighten | shrink 1mb' scan.pdf -o out.pdf
pdfblah do 'watermark "TOP SECRET" | protect s3cret' in.pdf -o out.pdf

dark, sepia, and ink navy are the recolor schemes; shrink is compress for people who think in words; straighten is rotate auto; bare sizes, watermark text, and passwords land where you'd expect. The full list fits in one breath on purpose.

Folders, and recipe files

Point the same line at a folder and it becomes a batch: every PDF flows through, originals untouched, failures reported per file, and bates start=auto numbers across files. Save the line as a file (newlines work like |, # comments welcome) and it's a recipe:

# discovery.recipe
bates prefix=EXH- digits=4 start=auto
pages --drop 1
watermark CONFIDENTIAL

pdfblah do @discovery.recipe evidence/ -o stamped/ --dry-run

One language, three homes: inline, recipe files, folders. --dry-run always shows the full plan, numbering included, before anything is written.

Finding your way

pdfblah help              # the map: every command, grouped by job
pdfblah help compress     # one command's manual, with a worked example
pdfblah verbs             # one line each; | marks pipeline verbs
pdfblah completions zsh > ~/.zfunc/_pdfblah    # tab completion (bash: eval "$(pdfblah completions bash)")

Completions are generated from the real parsers, so the tab key never lies about a flag.