Shell & CLI Integration

sgrep is designed for shell-first workflows. This guide covers aliases, fuzzy finding, and powerful pipeline combinations.

Shell Aliases

Bash / Zsh

Add to your .bashrc or .zshrc:

# Short alias for sgrep
alias sg='sgrep'

# Hybrid search (bm25 + semantic)
alias sgh='sgrep --hybrid'

# Search current directory recursively
alias sgw='sgrep "$(pwd)"'

# JSON output for parsing
alias sgj='sgrep --json'

Fish Shell

Add to ~/.config/fish/config.fish:

# Basic aliases
alias sg sgrep
alias sgh "sgrep --hybrid"

# Abbreviations expand on space
abbr sgj sgrep --json
abbr sgr "sgrep --json | jq"

# Function with current directory
function sgw
    sgrep $argv (pwd)
end

Nushell

# Define aliases in env.nu
alias sg = sgrep
alias sgh = sgrep --hybrid

# Custom command
def sgj [...args] {
    sgrep ...args --json | from json
}

FZF Integration

Basic FZF Integration

Search semantically and browse results interactively:

# Search with fzf preview
sgf() {
  local query="$1"
  local dir="${2:-.}"
  sgrep --json "$query" "$dir" | \
    jq -r '"\(.path)|\(.line)|\(.text)"' | \
    fzf --delimiter="|" \
        --preview='bat --color=always {1} --highlight-line {2}' \
        --preview-window=+{2}-/3
}

Open in Editor

# FZF with editor opening
sgfe() {
  local result=$(
    sgrep --json "$1" | \
    jq -r '"\(.path):\(.line):\(.text)"' | \
    fzf --delimiter=":" --preview="bat --color=always {1} --highlight-line {2}"
  )
  [ -n "$result" ] && ${EDITOR:-vim} "$result"
}

Ripgrep-style FZF

# Like rg+fzf but semantic
sg-fzf() {
  RG_PREFIX="sgrep --json"
  local query
  query=$(cat | tr '\n' ' ')
  FZF_DEFAULT_COMMAND="$RG_PREFIX $query" \
  fzf --sort --preview="[[ \$FZF_PREVIEW_COUNT -gt 100 ]] && echo 'Too many results' || sgrep {q} | head -100" \
      --phony --query "$query" \
      --bind "change:reload($RG_PREFIX {q} || true)"
}

Pipeline Examples

Find and Edit

# Edit matching files
sgrep "authentication" src/ | fzf --multi | xargs -r ${EDITOR:-vim}

# Edit specific lines
sgrep "bug fix" src/ | while read -r line; do
  vim "+$(echo $line | cut -d: -f2)" "$(echo $line | cut -d: -f1)"
done

Count and Group

# Count matches per file
sgrep --json "error handling" src/ | \
  jq -r '.path' | \
  sort | \
  uniq -c | \
  sort -rn

# Get top patterns
sgrep --json "." src/ | \
  jq -r '.text' | \
  sort | \
  uniq -c | \
  sort -rn | \
  head -20

Filter and Transform

# Filter by score threshold
sgrep --json "database" src/ | \
  jq 'map(select(.score > 0.7))'

# Extract unique paths
sgrep --json "test" src/ | \
  jq -r '.path' | \
  sort -u

# Format for git commit
sgrep --json "change" src/ | \
  jq -r '- \(.path):\(.line): \(.text)'

With bat for Preview

# Highlighted preview with bat
sgrep "function" src/ | \
  while IFS=: read -r file line text; do
    echo "$file:$line:$text"
    bat --color=always "$file" --highlight-line "$line"
  done | less -R

Parallel Processing

# Search multiple patterns in parallel
for pattern in "error" "warning" "todo"; do
  echo "=== $pattern ==="
  sgrep "$pattern" src/ &
done
wait

Combining with Other Tools

jq Integration

# Complex filtering
sgrep --json "security" src/ | \
  jq 'group_by(.path) | map({path: .[0].path, count: length}) | sort_by(.count) | reverse'

# Extract specific fields
sgrep --json "api" src/ | \
  jq -r '.[] | "\(.path)|\(.line)|\(.score)"' | \
  column -t -s '|'

xargs for Batch Operations

# Delete matching lines (careful!)
sgrep --json "deprecated" src/ | \
  jq -r '"\(.path):\(.line)"' | \
  while IFS=: read -r file line; do
    sed -i "${line}d" "$file"
  done

# Batch rename
sgrep --json "temp file" src/ | \
  jq -r '.path' | \
  sort -u | \
  xargs -I {} mv {} {}.bak
# Fast text filter first, then semantic
rg "TODO" src/ -l | xargs sgrep "urgent task"

# Combine results
{
  rg "error" src/ -n
  sgrep --json "error" src/ | jq -r '"\(.path):\(.line):\(.text)"'
} | sort -u

Shell Completion

Bash Completion

Create /usr/share/bash-completion/completions/sgrep:

_sgrep_completion() {
  local cur prev words cword
  _init_completion || return

  case "$prev" in
    --model)
      COMPREPLY=($(compgen -W "$(sgrep --list-models 2>/dev/null)" -- "$cur"))
      return
      ;;
    --output|-o)
      COMPREPLY=($(compgen -W "json text" -- "$cur"))
      return
      ;;
  esac

  if [[ "$cur" == -* ]]; then
    COMPREPLY=($(compgen -W "
      --help
      --version
      --json
      --hybrid
      --model
      --top-k
      --threshold
      --context
    " -- "$cur"))
  fi
}
complete -F _sgrep_completion sgrep

Zsh Completion

Create ~/.zsh/completion/_sgrep:

#compdef sgrep
_sgrep() {
  local -a arguments
  arguments=(
    '--help[Show help]'
    '--version[Show version]'
    '--json[Output JSON]'
    '--hybrid[Hybrid BM25 + semantic search]'
    '--model[Model to use]:model:(sgrep-code-v1)'
    '--top-k[Number of results]:number:'
    '--threshold[Score threshold]:threshold:'
    '--context[Lines of context]:context:'
  )
  _arguments -s $arguments
}

Fish Completion

Create ~/.config/fish/completions/sgrep.fish:

complete -c sgrep -f

complete -c sgrep -l help -d "Show help"
complete -c sgrep -l version -d "Show version"
complete -c sgrep -l json -d "Output JSON"
complete -c sgrep -l hybrid -d "Hybrid BM25 + semantic search"
complete -c sgrep -l model -d "Model to use" -x -a "sgrep-code-v1"
complete -c sgrep -l top-k -d "Number of results" -x
complete -c sgrep -l threshold -d "Score threshold" -x
complete -c sgrep -l context -d "Lines of context" -x

Quick Reference

# Essential commands
sgrep "pattern"                    # Basic search
sgrep --json "pattern"             # JSON output
sgrep --hybrid "pattern"           # Hybrid search
sgrep -e "category" < file.txt     # Classify lines

# Common pipelines
sgrep --json "pattern" | jq        # Parse JSON
sgrep "pattern" | fzf              # Interactive browse
sgrep "pattern" | xargs vim        # Edit results

# Directory operations
sgrep "pattern" src/               # Search directory
find . -name "*.rs" | xargs sgrep "pattern"  # Search file list

Tip: Create a ~/scripts/ directory with your custom sgrep wrapper functions and add it to your PATH.

.md
All docs →

Was this page helpful?