How the Project Started
In recent years, I have worked a lot with gRPC and ProtoBuf—the clear definition of services and models with automatic, type-safe stub generation for many languages has always thrilled me.
The Challenge with RESTful APIs
However, for purely RESTful APIs, gRPC is often not ideal. I tried gRPC Gateway, but particularly in Go, the approach felt too heavyweight.
Discovering TypeSpec
Since I started using TypeSpec, writing API specifications has become significantly more enjoyable than handcrafted OpenAPI files. The generated OpenAPI specs are solid and give me everything I need.
The Drawback of Code Generation
The catch lies in code generation: While TypeScript clients are usually usable, the results for Go—both on the client and server side—were disappointing. Satisfactory, idiomatic, clean Go code could not be generated from it, which is why I have often manually transferred server and client implementations until now.
This works as long as specs remain stable, but it remains an avoidable source of errors and costs unnecessary time.
The Extended Goal
My goal goes further: From a TypeSpec definition, I want to generate not only better clients but above all clean server stubs as well as additional tooling—such as a CLI client for interactive testing and a mock server for integration tests.
A New Approach
Initial experiments with my own TypeSpec emitter were promising. Instead of solving everything in one pass, I opted for a cleaner path: an intermediate format that contains all relevant information, and building upon that, a Go AST generator for real, maintainable Go code—without string templates.
From this, Spec CLI is taking shape step by step.
Initially, I simply wanted to build a convenient CLI tool similar to the integrated HTTP client in JetBrains IDEs—something to test APIs quickly and interactively without always resorting to Postman or curl.
As the idea evolved, it grew in scope: Why not generate an entire ecosystem from an API specification (first considered OpenAPI, later TypeSpec)—not just an interactive CLI client, but also client libraries, server stubs, mocks, and more?
This is why I named the project Spec CLI: “Spec” stands for the API specification as the central source, and “CLI” initially referred to the interactive command-line client that was the starting point—though it is now just one part of a larger whole.