CLI tools have always been broken

A 20-year shell veteran argues that CLI tools suffer from a systemic design flaw: each tool independently reimplements the same concerns — parsing, I/O formatting, compression, streaming, exit codes, and introspection — making consistency impossible without universal conventions. The problem, the author writes, is especially acute as AIs begin to require large libraries of CLI tools, since `--help` output is human-oriented prose rather than a machine-readable contract, structured data cannot be shared without lossy JSON or heavy Protobuf/Parquet frameworks, and feature addition or subtraction has no clear solution short of rewriting the program.

September 15, 2026 As one who’s lived in the shell for twenty years, I’m happy though not surprised to see how naturally the CLI fit into the AI world. However, there is a systemic flaw in CLI tooling. Each tool reimplements the same concerns: parsing, I/O formatting, compression, streaming, exit codes, introspection, and more. The builders, whether human or AI, navigate this design space independently. The only path to consistency is for all creators to agree on a wide range of conventions and write their code accordingly. Now this flaw is easy to miss when we use only a few CLI tools and only interactively. It bites when we use CLIs at scale and when we use them as functions in workflows. The problem is especially acute now as AIs begin to require large libraries of these CLI tools. I describe specific instances of this problem below: Tool self-descriptions are inconsistent . Suppose you want to loop over the tools in an environment and assemble a manifest of what each one does. CLI tools are supposed to be self-describing, so you should just be able to loop over all tools and call them with --help . But this fails. Some tools have no --help at all, some take seconds to produce it looking at you, Python , and many are creatively formatted. --help is prose meant for humans and usually written by hand, not a machine-readable contract derived from the tool itself. If you want to make a system of tools machine-accessible, you must maintain wrappers around the tools and update them as the tools change. Sharing complex data requires agreement on format . The UNIX philosophy that everything is a file makes interoperability easy: any tool can take anything as input. But if the input can be anything, only the most general operations are well formed. We can count bytes, grep for patterns, or concatenate streams; for anything more, the tool must know what the bytes mean. Passing structured data is trivial within a native program, but in a system of CLI tools this freedom is lost. A few special cases, like mp3 and png, get dedicated formats but structured data in general cannot be shared. Serializing to JSON is lossy integer widths vanish while serializing with Protobuf or Parquet requires agreeing on a heavy framework. Either way, tools depend on shared conventions and implicit knowledge of the upstream producers. Duplication of concerns multiplies dependencies and slows innovation . Much of what a CLI tool does is orthogonal to its core job, including compression, parallelism, serialization, argument handling. None of this is hard – the algorithms are well established. But each algorithm is re-wrapped in each language and each tool must independently decide which to import, which settings to use, and what flags to expose. In cases like compression, where downstream tools must understand the chosen format, the best option is often not the most efficient algorithm but the one most likely to be widely supported. These independent choices multiply dependencies, can break compatibility, resist evolution, and cannot be set for the whole system. Feature addition or subtraction . Every maintainer must balance between feature addition and weight reduction. New features may add dependencies, add distracting complexity, slow compile time, and increase maintenance costs. The user wants two powers the monolith denies: addition and subtraction. A compile-time plugin system could offer addition, but that’s heavy. In twenty years of writing CLI tools, I’ve never written a CLI plugin system. Subtraction, the removal of unwanted or problematic features, has no clear solution short of rewriting the program. So the creator chooses a set of features and the user must accept it. Commits to one face . A CLI tool is made of internal functions and an interface that exposes them. The functions are stable, testable and inherently compatible with many interfaces: a human at the shell types flags, a program passes values directly, a network client sends JSON, a model picks a tool and fills in arguments. The callers change but the functions do not. But when all we have is a CLI, every other interface must be laid over it. Network clients, library bindings, and MCPs all must generate system calls, follow human-oriented flag conventions, and pass stringified types. The connectivity is backwards – the CLI should be just one interface among equals. The solution is not a new best practices document or AI skill . The solution is also not to wrap every CLI tool in yet another layer. We do not need yet another framework layered on a flimsy foundation. I propose the opposite, rather than adding a layer, we subtract them. I propose we strip the CLIs down to their basal functions, annotate the functions, and distribute them directly. Then we automatically generate the CLIs and other concerns when needed. And no, I’m not suggesting an AI solution here, that would only change where and how conventions are defined. We need something we can trust. A compiler. I built the Morloc compiler https://github.com/morloc-project/morloc for this purpose. It allows functional composition across language under a common type system with CLIs, APIs, MCP models, and usage statements generated deterministically. This provides consistency by construction.