Problem
All errors — including actionable ones like "word not found" — are written to stderr:
$ sonaveeb-cli xyzxyz123
# stdout: (empty)
# stderr: error: word not found: xyzxyz123
# exit: 1
An agent reading stdout sees nothing and has to infer meaning from the exit code alone. The error message is the useful information.
Usage errors also print the full flag usage block to stderr, giving the agent nothing on stdout to act on.
Fix
Write structured errors to stdout so agents can read them directly:
error: word not found: xyzxyz123
Reserve stderr for debug/diagnostic output agents don't need to read (warnings, cache info, etc.).
For no-args invocation, print a brief error to stdout before the usage block:
error: no word provided
usage: sonaveeb-cli <word> [flags]
Exit codes can stay as-is (they're already well-differentiated: 1=not found, 2=usage, 3=error).
Reference
AXI Principle 6 — Structured errors & exit codes
Problem
All errors — including actionable ones like "word not found" — are written to stderr:
An agent reading stdout sees nothing and has to infer meaning from the exit code alone. The error message is the useful information.
Usage errors also print the full flag usage block to stderr, giving the agent nothing on stdout to act on.
Fix
Write structured errors to stdout so agents can read them directly:
Reserve stderr for debug/diagnostic output agents don't need to read (warnings, cache info, etc.).
For no-args invocation, print a brief error to stdout before the usage block:
Exit codes can stay as-is (they're already well-differentiated: 1=not found, 2=usage, 3=error).
Reference
AXI Principle 6 — Structured errors & exit codes