Exit codes
witr returns meaningful exit codes for use in scripts, CI pipelines and monitoring.
| Code | Meaning |
|---|---|
| 0 | Clean: process found, no warnings |
| 1 | Warnings: process found but has one or more warnings |
| 2 | Not found: no matching process or service |
| 3 | Permission denied: insufficient privileges |
| 4 | Invalid input: bad arguments or ambiguous match |
| 5 | Internal error: an unexpected failure occurred |
Why the split matters#
The distinction between 2 and 3 is the one that saves you false alarms. A monitoring check that treats both as "service is down" will page someone every time it runs without the privileges it needs. 2 means the process is genuinely not there. 3 means witr could not tell.
Similarly, 1 is not a failure — the process was found and is running. It means something about it is worth reading, like a public bind or a restart loop. See Warnings.
Branching on them#
witr nginx --short
case $? in
0) echo "All clear" ;;
1) echo "Warnings detected" ;;
2) echo "Process not running" ;;
3) echo "Need elevated privileges" ;;
4) echo "Invalid input or ambiguous match" ;;
5) echo "Internal error" ;;
esacCode 4 covers an ambiguous match — several processes matched your substring and witr declined to guess. Re-run with --pid, or add --exact.
More patterns in Scripting and CI.