Exit codes
AgentIdem Nebutex uses CLI exit codes so local scripts and CI systems can distinguish successful execution from unsafe results and operational failures.
Exit code summary
| Exit code | Meaning |
|---|---|
0 | Safe or successful |
1 | Unsafe result or replay mismatch |
2 | Operational or setup error |
Exit code 0
Exit code 0 means the command completed successfully.
Depending on the command, that can mean:
- a reliability test completed with a safe result
- a trace was recorded successfully
- a replay matched successfully
- the installed version was printed successfully
Example:
agentidem test examples.refund_agent:run
echo $?
A successful safe result should print:
0
Exit code 1
Exit code 1 represents a result-level failure.
For agentidem test, this means AgentIdem found unsafe behavior.
For agentidem replay, this means the replay did not match the recorded behavior.
Examples include:
duplicate successful write detected
or:
replay mismatch
This exit code is different from an operational failure because AgentIdem successfully ran the command and produced a meaningful result.
Exit code 2
Exit code 2 represents an operational or setup error.
Examples can include:
- invalid target syntax
- module import failure
- missing target function
- baseline execution failure
- invalid trace input
- file loading failure
- other setup or execution errors
These problems prevent AgentIdem from producing the intended test, record, or replay result.
test command
For:
agentidem test examples.refund_agent:run
the expected exit code model is:
| Exit code | Meaning |
|---|---|
0 | Test completed and result is safe |
1 | Test completed and result is unsafe |
2 | Test could not complete because of an operational or setup error |
record command
For:
agentidem record examples.refund_agent:run --trace trace.json
the expected exit code model is:
| Exit code | Meaning |
|---|---|
0 | Trace recorded successfully |
2 | Recording failed because of an operational or setup error |
record is not primarily a safety-result command, so an unsafe-result exit code is not normally the result of recording a single execution.
replay command
For:
agentidem replay examples.refund_agent:run --trace trace.json
the expected exit code model is:
| Exit code | Meaning |
|---|---|
0 | Replay matched |
1 | Replay mismatch |
2 | Replay could not complete because of an operational or setup error |
version command
For:
agentidem version
the expected exit code model is:
| Exit code | Meaning |
|---|---|
0 | Version printed successfully |
2 | Operational or setup error |
Using exit codes in shell scripts
You can inspect the previous command's exit code with:
echo $?
For example:
agentidem test examples.refund_agent:run
echo $?
Using exit codes in CI
CI systems usually fail a step automatically when a command exits with a non-zero code.
That means:
agentidem test examples.refund_agent:run
can be used directly as a reliability gate.
A safe result exits with:
0
An unsafe result exits with:
1
An operational or setup error exits with:
2
This distinction helps CI systems separate:
the agent was tested and found unsafe
from:
the test could not run correctly