# JSON Output

> **TL;DR** — Use `--json` to pipe sgrep results into jq, scripts, or other tools. Grep-compatible exit codes included.

## Basic JSON

```bash
sgrep --json "parse configuration" src/
```

Output:

```json
[
  {
    "path": "src/config.rs",
    "line": 42,
    "score": 0.847,
    "content": "/// Parse the TOML configuration file and return validated settings"
  },
  {
    "path": "src/cli.rs",
    "line": 18,
    "score": 0.723,
    "content": "// Load and validate CLI configuration from args + env"
  }
]
```

## Pipeline Examples

```bash
# Open the best match in your editor
sgrep --json "authentication" src/ | jq -r '.[0].path' | xargs $EDITOR

# Count matches above threshold
sgrep --json --threshold 0.7 "memory leak" src/ | jq length

# Get just file paths (unique)
sgrep --json "error handling" src/ | jq -r '.[].path' | sort -u

# Feed into ripgrep for exact refinement
sgrep --json "database query" src/ | jq -r '.[].path' | xargs rg "SELECT"
```

## Exit Codes

sgrep follows grep conventions:

| Code | Meaning |
|------|---------|
| `0` | Matches found |
| `1` | No matches above threshold |
| `2` | Error (bad args, missing files, etc.) |

This means you can use sgrep in shell conditionals:

```bash
if sgrep --threshold 0.8 "security vulnerability" src/ > /dev/null 2>&1; then
  echo "Potential security-related code found"
fi
```

## JSON Schema

Each result object contains:

| Field | Type | Description |
|-------|------|-------------|
| `path` | string | File path relative to search root |
| `line` | number | Line number of the chunk start |
| `score` | float | Cosine similarity (0.0–1.0) |
| `content` | string | The matched text chunk |