Skip to content

Usage

Core Commands

Command Purpose
cgrep s "query" [path] text/code search
cgrep d <symbol> definition lookup
cgrep r <symbol> references lookup
cgrep c <function> caller lookup
cgrep symbols <name> symbol search
cgrep read <file> smart file read
cgrep map --depth 2 quick codebase map
cgrep dep <file> reverse dependents
cgrep status index + daemon status

Daily Workflow

Human CLI fast path:

# 1) Find candidate files
cgrep s "authentication middleware" src/

# 2) Read focused context
cgrep read src/auth.rs

# 3) Jump to implementation / usage impact
cgrep d handle_auth
cgrep r handle_auth
cgrep c handle_auth

If the task is broad or ambiguous, use cgrep agent plan "..." as an optional stage 0 before this flow.

Search Scoping (Most Important)

Use scope early to reduce noise and tokens.

# Path scope
cgrep s "DispatchKeySet" -p c10/core

# File type scope
cgrep s "token refresh" -t rust

# Changed files only (default revision: HEAD)
cgrep s "retry" -u

# Context lines
cgrep s "evaluate_function" -C 2

# Result limit
cgrep s "TensorIterator" -m 10

Agent-Friendly Output

# Deterministic compact payload
cgrep --format json2 --compact s "PythonArgParser" -p torch/csrc/utils

# Score explain (keyword mode)
cgrep --format json2 --compact s "target_fn" --explain

Profiles and Budgets

# Human-friendly defaults
cgrep s "auth flow" -P human

# Agent-focused payload control
cgrep s "auth flow" -P agent -B tight --format json2 --compact

mode vs profile (Important)

  • --mode chooses the search engine path:
  • keyword
  • semantic (experimental)
  • hybrid (experimental)
  • --profile tunes retrieval defaults and payload shape:
  • human
  • agent
  • fast

Examples:

# Engine choice
cgrep s "auth flow" --mode keyword

# Payload / retrieval defaults
cgrep s "auth flow" --profile agent -B tight --format json2 --compact

Use profile when you want more compact, agent-friendly output. Use mode only when you intentionally want a specific search engine.

Indexing Behavior (Simple)

  • search/read/definition/... commands can auto-bootstrap index if missing.
  • You can still prebuild manually with cgrep index.
  • For continuous session updates, run cgrep daemon start and stop with cgrep daemon stop.

Important Notes

  • Empty queries are rejected.
  • If query starts with -, pass --:
cgrep s -- --help
  • auto is not a CLI search mode. For CLI search, use keyword|semantic|hybrid.
  • semantic and hybrid modes are experimental and require embeddings index.

Next