Skip to content

AXI P6: Write errors to stdout, not stderr #3

Description

@LarsEckart

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions