About error reporting
Command execution in CONGA separates error evaluation from process termination. The execution methods app.Run and app.RunContext return command-line mistakes and runtime failures as plain error values instead of calling os.Exit. Callers decide how to handle failures, whether by inspecting the error directly or delegating terminal formatting and exit status codes to the optional app.Exit(err) convenience method.
Errors as values across the pipeline
Section titled “Errors as values across the pipeline”Many command-line libraries end the process when parsing fails. The standard library’s flag.Parse prints the error and calls os.Exit on invalid input. A test of such a program has to run it as a subprocess, and its commands can’t be embedded in a server, a GUI application, or a test harness.
In CONGA, app.Run() and app.RunContext(ctx) parse, coerce, validate, and run the command, then return an ordinary Go error:
nilon clean execution, including built-in commands. Requests for--help,--version, and opt-in diagnostics like--whyand--completionrender to standard output and returnnil. A help request succeeds, soif err != nilhandles only real failures.- A usage error when command-line input violates syntax, naming, or value constraints.
- An
ErrConfigfailure when a value from an environment variable, a configuration file, or a default tag fails to coerce or validate. These exit with status 1 and name the value’s origin in the message. - A runtime error when the active command’s
Runmethod or a lifecycle hook returns a failure.
Pipeline errors versus programmer defects
Section titled “Pipeline errors versus programmer defects”CONGA splits failures by who has to fix them:
- Pipeline errors are user mistakes and execution failures, such as invalid flags, unknown subcommands, values that fail to parse, violated constraints, missing arguments, and failures returned by a command’s
Runmethod. They are normal conditions for a CLI, soRunandRunContextreturn them aserrorvalues, and the application decides how to inspect, log, and exit. - Programmer defects are developer contract violations, such as passing a nil
context.ContexttoRunContext, attempting to execute anAppinstance a second time, registering duplicate or empty predictor names, or misusing a builder (ConfigPathswith no paths). CONGA panics on these with a fixed message, such as"conga: nil Context"or"conga: App already executed", as Go code conventionally does for programmer errors. A panic marks a defect that needs a code change, not an error to handle at run time. Schema errors are not panics. Schema build returns them fromRunasErrSchema. Panics lists every panic and its message.
The optional Exit convenience
Section titled “The optional Exit convenience”Standalone command-line applications translate errors into standard error messages and an exit status code. app.Exit(err) accepts the value returned by app.Run or app.RunContext(ctx) and maps it to a POSIX status. A usage error exits with status 2, so a script can tell that the command failed before any work began because its command line was wrong. Exit codes lists every status.
Exit terminates through the configured exit function (app.ExitFunc, default os.Exit). It returns only when that function returns without terminating. All PostRun and Finally hooks complete inside app.Run, so the teardown work is already done by the time Exit runs.
Exit is optional. Applications that embed CLI commands, collect telemetry, or format errors using structured loggers like slog can omit Exit and handle the returned error value directly. When callers do use Exit, setting app.ExitFunc(handler) intercepts the requested exit status code without killing the test process, allowing tests to verify exit behavior in-process.
Self-describing value errors
Section titled “Self-describing value errors”Exit matches the help it prints to the kind of mistake. Unknown flags, unknown subcommands, and missing required positional arguments are interface-discovery mistakes, so Exit pairs them with a syntax usage block or --help hint. Command-line coercion and constraint failures already name the flag and the offending value, so they render without the usage block. Environment-, configuration-, and default-sourced value failures are not usage errors at all, so they exit with status 1 and print the error line alone. Printing a 40-line usage screen below a value error scrolls the terminal window and buries the actual message under redundant text. Errors and exit codes lists which failures count as self-describing.
Categorical classification without concrete coupling
Section titled “Categorical classification without concrete coupling”Every pipeline failure wraps one of five sentinel errors, such as ErrParse or ErrConfig, and conga.IsUsageError(err) reports whether it is a usage error. The concrete error types stay unexported, so their representation can change without breaking callers. Errors and exit codes catalogs the sentinels and the UsageError interface.
For testing patterns, see How to test a command.