Docs / Reference
Exit codes
What each ivralo command's exit status means, for scripts, CI jobs and schedulers. Most commands exit 0 on success and 1 when something went wrong; the ones below give 1 and 2 separate meanings.
The rule
- 0: it did what was asked.
- 1: it ran, and the answer is no: the run failed, the check stopped, the report was not written.
- 2: it could not start, or the arguments were wrong. Nothing was attempted.
Errors and questions go to stderr; in a pipe, stdout carries only the result. Wrong usage, such as an unknown option, a missing argument or an unknown --profile, exits 2 for every command. So does a --model that cannot be used: a bare name that looks like a provider's model, a reference that does not parse, or a provider with no key.
Commands with their own codes
| Command | 0 | 1 | 2 |
|---|---|---|---|
ivralo ask | The run ended well. | The run failed, the prompt was empty, or --plan stopped at a step or found nobody to approve it in a pipe without --yes. | A flag combination that does not go together: --format other than text or json, --plan with --format json or --quiet, --job with --format json, --quiet or --image, --changeset with --plan or --job. |
ivralo ask --via-api | The run ended well. | It did not. | The request never ran: no server, no token, a version mismatch, or a refusal. |
ivralo plan | The plan was drafted, or with --job, the job completed, parked or is blocked. | Nothing to plan, or the job failed or was cancelled. | --job with --json. |
ivralo incident | A report was written. | The run ended without one. With --format json one object is still printed, with outcome: null and the reason. | The investigation could not start: the workspace, the bundle, a hosted model without --hosted, the database. |
ivralo pilot run | The report was written. | It was written, and the match rate is under --fail-under. | It could not start. |
ivralo verify | Every stage passed. | It stopped at a failing stage. | Nothing to verify with: no declared commands, an untrusted folder, a bad request. |
ivralo why | Every branch of the claim reaches a recorded source. | It does not, or the claim was not found. | The run could not be read. |
ivralo replay | The replay held to the recording. | It diverged. | Nothing could be read. |
ivralo record | The cassette was written. | The run could not be read. | |
ivralo trust | Done. | Refused: the path is not a folder, there is no terminal to ask and no --yes, or the record could not be written. | |
ivralo resume | The job went on, or ended well. | A parked job was given no answer: its question is printed and nothing changes. The job failed. | More than one of --approve, --approve-job and --reject. |
ivralo bisect | The search ended. | It failed. | |
ivralo jobs run | A job completed, parked, is blocked behind another, or there was nothing to run. | The job failed or was cancelled, or a job a dead process left running has to be resumed or cancelled first. | |
ivralo index | The index is up to date. | It could not be built. | --all without --rebuild, or --semantic without --code. |
ivralo init | Everything is in place. | A row is not in place; the command to run again is printed. | There is no home init may write to: none was named, and the one found is the folder you are in, or none was found. Name one with --home or IVRALO_HOME. |
ivralo serve | It could not start: the port is taken, the home may not hold the token file, or the PostgreSQL ivralo made would not start. |
ivralo serve runs until it is stopped, so it exits by signal: 130 after Ctrl+C (SIGINT) and 143 after SIGTERM, which is 128 plus the signal number. A service manager should treat those as a clean stop.
Everything else
These exit 0 on success and 1 on any failure, with the reason on stderr:
| Command | 1 means |
|---|---|
ivralo | There is no terminal for the session, or the workspace could not be entered. |
ivralo doctor | At least one row is red. |
ivralo job, ivralo cancel, ivralo jobs | The job was not found, or the database could not be reached. |
ivralo changeset and its subcommands | No such changeset, a landing refused over your own edits, or a drop you declined. |
ivralo schedule and its subcommands | The OS scheduler refused, the schedule does not exist, or a run failed. |
ivralo skills lint --strict | An error-level finding exists. Without --strict, findings do not change the exit. |
ivralo skills and its other subcommands | The skill could not be installed, found, written or removed. |
ivralo mcp and its subcommands | The entry is invalid, the file could not be written, or mcp test could not connect. |
ivralo memory and its subcommands | The memory was not found, or the database could not be reached. |
ivralo google and its subcommands | Sign-in failed or is not set up. |
ivralo history, ivralo restore | No such file or version. |
ivralo search | The index could not be searched. |
ivralo eval has codes of its own for its bar and its options; see Evals.
In a script
ivralo incident incident/ --format json > report.json
case $? in
0) echo "report filed" ;;
1) echo "no report: see the reason in report.json" ;;
2) echo "could not start" >&2; exit 2 ;;
esac
# Fail a CI job when the project's checks fail (1) or cannot run (2).
ivralo verify --scope full --yes || exit $?