Exit Codes

Exit Codes

Columbus uses stable, scriptable exit codes. Pair them with the --json error envelope (JSON Contract & Errors) for precise handling.

Code	Meaning
0	Success (including "usable with warnings" — e.g. memory drift)
1	Runtime error (e.g. symbol not found)
2	Usage error (bad flags/arguments)
3	Not initialized / index missing (run columbus install / columbus reindex)
4	Transient / retryable (e.g. index writer locked)

Examples

Not initialized (3):

$ columbus search foo          # in a dir with no .columbus.json
error [NOT_INITIALIZED]: no .columbus.json found
  hint: run columbus install
$ echo $?
3

Not found (1):

$ columbus show symbol DoesNotExist --json
{"command":"symbol","error":{"code":"NOT_FOUND","message":"symbol not found: DoesNotExist"},"ok":false,"schema_version":1}
$ echo $?
1

Notes

• Warnings are not failures. Memory/reference drift exits 0 — it is surfaced, never fatal.
• 4 is retryable. A locked index writer means another index is running; back off and retry.
• Diagnostics print to stderr; results to stdout.

Related

JSON Contract & Errors · Troubleshooting