Decisions › D13
The command line is the seam: any command that exits 0 to 3 is a diagnostic
Context
Zach found running a command from the page a very nice interface, because an AI or anything else can use it too, and the diagnostics only attach the commands, run the process and read the result. He asked whether all the controls should register themselves as command lines, so diagnostics never has to care about any internal communication.
The decision
Yes, and it already was: a driver is an executable that speaks describe, diagnose and act, and every utility runs a command line. Round 3 added the stock Monitoring Plugins (Nagios) API: any command whose exit code is 0, 1, 2 or 3 (OK, WARN, CRITICAL, UNKNOWN), whose first line of output is the message and whose text after a | is performance data, is a diagnostic. A simple check needs one TOML file and no code.
Why
“CLI can be used by AI or anything”
Zach Yamaoka, notes, 23 Oct 2026
“Should basically like all of the controls register them selves as CLI? then diagonistics never cares about any internal communication or anything... which I think is a good stable seem”
Zach Yamaoka, notes, 23 Oct 2026
Options considered
| Option | Verdict | Reason |
|---|---|---|
| An importable plugin API (Python entry points) | Not the contract | It scored 4 in round 1, but one environment must hold every driver's dependencies, and a driver in another language is shut out. |
| Our own JSON-lines command line | The contract | A driver keeps its dependencies, its language and its crashes. |
| The stock Monitoring Plugins exit-code convention, for simple checks | Added | Twenty-five years of use; any existing check script works unchanged. |
Consequences
- A check of the root disk is a few lines of TOML that name the command. Its performance data becomes typed measurements.
- Because the seam is a command line, a person, a script and an AI all run the same thing.
Evidence
- IO diagnostics v1: the first end-to-end buildReport, 2026-10-22. Evidence for this decision.
- Round 3 briefContract doc, 2026-10-23. What was settled in round 3 (resizable panes, warning colours reserved, quieter utilities) and the three sets of proposals.
- IO diagnostics v1: build planContract doc, 2026-10-22. The decisions, the plugin boundary (a subprocess speaking JSON lines), the lanes, and the interfaces frozen between them.
Commits in the app's repository (private):
383fa9a2026-10-23 Host round 3: Monitoring Plugins checks as plain CLI diagnostics