SpecGate CLI
SpecGate was the first project I built as part of Beyond the Docs. I wanted to understand what goes into designing a CLI and how those design decisions shape the developer experience.
SpecGate is a command-line tool for enforcing OpenAPI specification (OAS) readiness. It evaluates OAS files against a set of readiness rules and surfaces errors and warnings. SpecGate catches missing operation summaries, undocumented responses, placeholder server URLs, and other issues that can make APIs harder to use and document.
Rather than focusing on style, SpecGate focuses on readiness: is the OAS ready to drive the documentation, SDKs, and other artifacts developers rely on?
How I built it
I initially built a protoype CLI called SmartDoc using Python and Typer. SmartDoc used a large-language model (LLM) from OpenAI called GPT-5-mini to analyze OAS files and surface missing documentation.
As I continued developing the project, I realized that relying on the LLM for every check wasn't the right approach. The LLM's responses could varied between runs, meaning that a user could run SmartDoc multiple times against the same OAS file and receive different results. Ideally, the results should be predictable and consistent each time.
To address these issues, I rebuilt the project in Go using the Cobra CLI framework and redesigned it around deterministic rules. Instead of using an LLM to analyze the OAS, SpecGate uses hard-coded validation rules to determine whether the OAS is ready to be used. Defining and testing those rules took some work, but it resulted in predictable responses every time. Throughout the development process, I used GitHub Copilot as a coding assistant for debugging, refactoring, and speeding up implementation.
SpecGate does use an LLM for the specgate advise command, which generates suggestions for missing summaries and description. The responses do vary, but the CLI is only providing recommendations.
What I learned
I learned a lot building SpecGate. 😁
Deterministic tools may be harder to build, but produce predictable, consistent, and fast output
Building SmartDoc was easier than SpecGate because the core functionality involved sending an OAS file to GPT-5-mini and processing the response. With SpecGate, I had to define the validation rules, implement them, and test the CLI's logic. However, the hard work paid off: the results are delivered quickly, and the results are predictable.
While it took more time to build SpecGate, I'd rather have deterministic rules that make the decision and use an LLM where it adds value rather than solely relying on an LLM's judgment.
Human-readable output is key
In an earlier version of SpecGate, the CLI output was long and difficult to scan:
ERRORS
------
Missing operation summaries for 1 operation(s):
- GET /menu/{itemId}
Missing error responses (4xx/5xx/default) for 4 operation(s):
- POST /orders
- GET /loyalty/{customerId}
- POST /loyalty/{customerId}
- GET /menu
WARNINGS
--------
Missing operation descriptions for 3 operation(s):
- GET /menu/{itemId}
- GET /loyalty/{customerId}
- POST /loyalty/{customerId}
Every issue had its own section, so if the OAS had multiple issues, the output would be hard to scan.
This realization changed how I think about CLI design. I was focused on giving the developer everything they needed to know, but was I presenting it a way that was clear, human-readable, and easy for developers to understand? Looking at the original output, I didn't think so.
So, I decided to redesign the UX for SpecGate. Developers should be able to understand the overall status of their OAS at a glance, then choose whether they want more detail.
Now, SpecGate displays a concise summary by default. The detailed diagnoses are behind the --verbose flag. The result is easier to scan while still making the full information available when it's needed.
specgate check oas.json
Loaded config from .specgate.yaml ✅
oas.json - 2 errors, 2 warnings
I plan to make a few more improvements to the UX, but I'm happy with it for now.
Tech stack
- Go
- Cobra CLI framework
- OpenAI's GPT-5-mini model (for
specgate adviseonly)