#cli

The shape I give small tools: one file, one job, sections in a fixed order, an exit-code contract at the top, and three ways in for input — plus its Bash variant for generators, and when a tool outgrows it.

SMTP and IMAP credentials fail late and far from their cause: a reset email that never arrives. A small check proves both directions first, with a tokenised test message, a read-only inbox check, and broken config kept distinct from a broken server.

Every search result gives the same answer for this: a LibreOffice command. I use a different engine, for four specific reasons — and the rest of the tool is the cost of talking to a converter built for a document server rather than for a command line.

A recording is two halves and usually only one is broken. Cleaning up the audio repeatedly, without watermarks or caps, needed a filter already compiled into ffmpeg — and eight further decisions that had nothing to do with noise, including the one whose proof is a matching hash.

Editing, building, and flashing had all moved to the terminal; reading serial output was the one job still holding a vendor IDE open. Replacing it took a program already on the machine, plus six decisions the IDE had been making silently.

A project copied from a template still carries the old name in its config, namespace, table prefix and comments. Replacing it everywhere takes one three-line command, and its value lies in the six decisions inside that line.

What did I work on last month? The answer is in the commit log, but commits are written for git and my future self. Forty-five lines of flags turn that log into notes for the person asking — a transformation of the audience, not of the data.

Commands I run four times a year are the expensive case: I remember their shape, not their syntax, and get something plausible but wrong. Three scripts hold the decisions, and their guards depend on whether there is a choice I could get wrong, not on danger.

Photos into one PDF, a PDF under two megabytes, a layout inspected page by page — usually done by uploading to a stranger's website. Three small tools do it locally with Pillow and Ghostscript; the only real decisions were which defaults to bake in.

Retyping long Docker commands costs seconds, invites typos and taxes working memory. Ten short executables on PATH removed that cost; the interesting decisions were why not aliases, how to keep names guessable, and why one of them is 260 lines long.

A storage server that answers a connection only proves a process is listening. I check each capability separately — browser uploads via presigned URL, private buckets refusing strangers, large files through the proxy — before any application depends on it.

A failed login in a half-built service is either a misconfigured identity provider or wrong code. I rule out the first by rehearsing a full login with my own tool before writing any app, and found compliant providers still disagree on tokens and claims.