A command-line tool built to automate an internal task gets used enthusiastically by the person who wrote it and largely ignored by everyone else on the team, and the reason is rarely that the underlying automation is wrong — it's that CLI usability has its own discipline, distinct from application development, and it's usually skipped when the tool was built quickly to solve one person's immediate problem.
Help text is the first thing that determines adoption, and it's the thing most internal tools skip entirely. A tool with no help flag, or one that dumps a wall of undifferentiated options with no examples, forces every new user to either read the source code or ask the author directly — both of which are exactly the friction that stops a useful tool from spreading past its creator. A help output with a couple of concrete usage examples, not just a list of flags, is what actually lets someone adopt the tool without a conversation.
Sensible defaults matter more than configurability for adoption. A tool that requires five flags to be specified correctly before it does anything useful will be used rarely and incorrectly; the same tool with defaults covering the common case, and flags only needed to override that default for the unusual case, gets used constantly because the common path just works. Configurability is valuable for the power user and should never be the price of entry for the common one.
Error messages deserve the same care given to API error responses elsewhere on this site — a failure that prints a raw stack trace or an opaque error code tells a user something went wrong and nothing about what to do next, while a clear message explaining what was expected and what to try instead is what actually lets someone self-serve past a mistake rather than interrupting whoever wrote the tool. A CLI tool that's genuinely pleasant to use when things go wrong, not just when they go right, is the one that survives past its author's own use of it.
