Exit Codes¶

Reference for clinvk exit codes based on current implementation behavior.

Overview¶

clinvk uses process exit codes for scripting and automation.

Code	Name	Description
0	Success	Command completed successfully
1	General Error	Validation/config/runtime error, or aggregated subcommand failure
6	Timeout	Command exceeded `unified_flags.command_timeout_secs` and timeout bubbled to top level
2+	Backend Exit Code	Propagated backend CLI exit code (for `prompt` / `resume` paths)

Code	Meaning
0	Success
1	General error before backend exit propagation
6	Timeout (`command_timeout_secs`)
2+	Backend CLI exit code is propagated

Code	Meaning
0	All units succeeded
1	One or more units failed (including timeout inside a unit)

Code	Meaning
0	Command succeeded
1	Command failed

When unified_flags.command_timeout_secs is set to a positive value:

Backend process timeout is detected and treated as a timeout error.
Top-level timeout errors are normalized to exit code 6.
In aggregate commands (compare / chain / parallel), per-unit timeout is treated as unit failure and contributes to aggregate exit code 1.

Example:

# config.yaml
unified_flags:
  command_timeout_secs: 5

clinvk "long running task"
echo $?  # 6 if timed out at top-level prompt/resume path

clinvk "task"
code=$?

case $code in
  0)
    echo "success"
    ;;
  6)
    echo "timeout"
    ;;
  *)
    echo "failed with code $code"
    ;;
esac

set -e

clinvk "step 1"
clinvk "step 2"

Do not assume historic code mappings that are not listed above.
If you depend on specific behavior in CI, pin your workflow to the documented contract in this file.