smolbren exit codes for shell scripting

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

Code	Name	Meaning
`0`	ok	Command succeeded.
`1`	internal	An unexpected internal error occurred.
`2`	usage	Invalid arguments or flags were passed.
`3`	vault_not_found	No vault with that name is registered in config, or no default vault is set and `--vault` was not provided.
`4`	note_not_found	The note ID passed to `get`, `links`, or `backlinks` does not exist in the index.
`5`	index_missing	The vault is registered but has not been indexed yet — run `smolbren index` first.
`6`	embeddings_missing	`similar` or `search --hybrid` was called before embeddings exist — run `smolbren embed` first.
`7`	model_error	The embedding model failed to download or initialize. Check network access (the model downloads from Hugging Face on first use), or delete `~/.smolbren/models/` to clear a corrupt cache.

Shell scripting examples

Checking the exit code after a search

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.

Commands

Output & Errors

smolbren exit codes for shell scripting

Exit code reference

Shell scripting examples

Checking the exit code after a search

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

Distinguishing vault errors from missing notes

​Exit code reference

​Shell scripting examples

​Checking the exit code after a search

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

​Distinguishing vault errors from missing notes

Exit code reference

Shell scripting examples

Checking the exit code after a search

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

Distinguishing vault errors from missing notes