> ## Documentation Index
> Fetch the complete documentation index at: https://smolbren.com/llms.txt
> Use this file to discover all available pages before exploring further.

# smolbren exit codes for shell scripting

> smolbren uses structured exit codes so scripts and agents can handle errors programmatically. Reference for all exit codes and their meanings.

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](/cli/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.                          |

## Shell scripting examples

### Checking the exit code after a search

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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
```

<Note>
  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.
</Note>

For details on the stderr JSON structure (`error` and `code` fields) that accompanies non-zero exits, see [Output Format](/cli/output-format#error-output).