Skip to main content
smolbren uses non-zero exit codes to signal distinct failure conditions. Scripts and agents can branch on error type by inspecting $? directly — no need to parse error messages, which may change between releases. This pairs with the structured stderr JSON (see Output Format) for cases where you need both the code and a human-readable explanation.

​
Exit code reference

CodeNameMeaning
0okCommand succeeded.
1internalAn unexpected internal error occurred.
2usageInvalid arguments or flags were passed.
3vault_not_foundNo vault with that name is registered in config, or no default vault is set and --vault was not provided.
4note_not_foundThe note ID passed to get, links, or backlinks does not exist in the index.
5index_missingThe vault is registered but has not been indexed yet — run smolbren index first.

​
Shell scripting examples

smolbren search "knowledge graph"
if [ $? -ne 0 ]; then
  echo "Search failed — see stderr for details" >&2
  exit 1
fi

​
Auto-indexing on a missing index (exit code 5)

A common pattern in setup scripts is to index automatically the first time a vault is used: 
smolbren search "knowledge graph"
if [ $? -eq 5 ]; then
  echo "Index missing — running smolbren index first"
  smolbren index
  smolbren search "knowledge graph"
fi

​
Distinguishing vault errors from missing notes

result=$(smolbren get "$NOTE_ID" 2>/tmp/smolbren_err)
code=$?

if [ $code -eq 0 ]; then
  echo "$result" | jq .
elif [ $code -eq 4 ]; then
  echo "Note '$NOTE_ID' not found in index." >&2
elif [ $code -eq 3 ]; then
  echo "No vault configured. Register one with: smolbren vault add" >&2
else
  cat /tmp/smolbren_err >&2
  exit $code
fi
Exit code 2 is emitted by the argument parser when a command is malformed — for example, a missing required argument or an unrecognised flag. The error message will appear on stderr as plain text (not JSON), because the error occurs before smolbren’s own error handling runs.
For details on the stderr JSON structure (error and code fields) that accompanies non-zero exits, see Output Format.