Nobody reads the manual
Let me describe the actual lifecycle of a user meeting your CLI tool, because it’s a bit humbling. They run it. It doesn’t quite do what they expected. They run it again with --help. They get a wall of monospaced flag …
Tags
66 pages
go-tool-base
BDD where it earns its place, and nowhere else
I have a slightly complicated relationship with BDD. I’ve watched it turn a tangled test suite into something the whole team could read and reason about, and I’ve watched it turn a perfectly good unit test into a …
An AI interface that fits on one screen
The moment you decide a CLI tool should talk to an LLM, there’s a strong gravitational pull towards reaching for LangChain, or one of its many relatives. It’s the obvious move. It’s also, for most CLI work, a bit like …
The config key that quietly did nothing
I once spent the better part of an hour convinced a timeout setting was broken. I’d set it in the config file, the tool ignored it, and the code that read it looked perfectly correct. The setting was tiemout. I’d typed …
One variadic, and I'd already spent it
I had a constructor I was rather pleased with. Hand go-tool-base’s root command its props and as many sub-commands as you like, and off it goes. Then I needed to thread some config file paths through it, reached for the …
Half your users don't have eyes
Run a command in your favourite CLI tool and look at what comes back. Colour. Neatly aligned columns. A friendly little summary sentence. Lovely… if you happen to be a human with eyes. But a good half of any tool’s users …
Lifecycle management for when your CLI grows up into a service
There’s a moment in the life of a lot of CLI tools where they stop being a CLI tool. Nobody quite decides it. It just happens. Someone needs the thing to also expose a little HTTP endpoint, or poll a queue, or run a …
Middleware for CLI commands, not just web servers
Every CLI tool past a certain size grows a category of logic that doesn’t really belong to any one command, and yet has to happen for loads of them. Timing. An auth check. Panic recovery, so a crash becomes a clean error …
A logging interface that doesn't leak its backend
The same tool, in two different lives, wants two completely different kinds of log. On my laptop I want logs I can actually read: colour, alignment, friendly timestamps. The very same tool running as a daemon in a …
Errors that tell the user what to do next
Here’s an error message I’ve been on the receiving end of more times than I’d care to count: error: failed to read config file True. Also completely useless! I now know something is broken and I haven’t the faintest idea …
