Documentation

CLI reference

Every command works on the current repository or on the one you pass with --root DIR. The first structured query builds the index. Ordinary grep invocations go straight to the system grep: a first word that is not a greppy command reaches grep as the pattern. greppy --help and greppy <command> --help show the exact surface of your installed binary.

Command Answers
greppy who-calls S [S …] every place that calls or uses S (incoming CALLS and USAGE edges)
greppy callees S [S …] the indexed definitions S calls directly, with their locations
greppy brief S [S …] doc sentence, signature, one line per call or branch in the body, plus the callers; structs, enums and traits appear in full
greppy impact S [S …] the transitive reach with hop distance; --direction incoming (default) or outgoing, --depth N (default 6), --edge TYPE
greppy path --from A --to B every call chain as a tree of call sites; --edge CALLS|USAGE|TYPE_ASSIGN|IMPORTS (default CALLS)
greppy where-am-i the repository at a glance: layout with definitions per folder, languages, entry points, test roots
greppy graph-locate FILE:LINE the innermost symbol enclosing a location (or --file F --line N)
greppy fan-in / greppy fan-out most-called / most-calling symbols; --edge CALLS|USAGE|USES|TYPE_REF|IMPORTS (default CALLS)
greppy trace --symbol S the call graph step by step; --direction outgoing|incoming (default outgoing), --edge CALLS|USES|TYPE_REF|IMPORTS (default CALLS), --depth N (default 4)
greppy search-graph --name NAME structured search for graph nodes

With impact, the incoming direction without --edge follows all reference edges, and outgoing follows CALLS. A - in place of a symbol reads the symbols from the pipe.

Command Finds
greppy search "WHAT IT DOES" definitions by meaning, ranked, up to eight hits
greppy search-symbol NAME definitions whose name contains NAME
greppy search-pattern REGEX every matching source line, including comments, strings and config, with the enclosing definition; --fixed for literal text
greppy plus QUERY mixed ranking from text, symbol, meaning and graph signals; --k N (default 10), --explain
greppy expand ID the evidence pack a previous result offered

--kind function|method|class|struct|enum|trait restricts search, search-symbol and search-pattern. With many hits, search-pattern shows a sample spread across the files, with the total count; --all prints every line.

Read source

Command Returns
greppy read S [S …] definitions as source bytes, with the docs and attributes directly above them; --head M, --tail N
greppy read-smart S [S …] source with nested blocks folded; --depth N (default 1)
greppy read-file PATH [PATH …] files in pages of 400 lines; --lines A:B, --all, --outline (outline of the indexed definitions, 0.4.1)

--handle on any read command also prints an edit handle for each printed span.

Edit transactionally

Command Does
greppy replace S [NEW] replaces a definition; --body replaces its body
greppy replace-span H [NEW] replaces the span a handle names; refuses if the file has changed since
greppy replace-text F OLD [NEW] replaces OLD when it occurs exactly once; --expect N, --regex
greppy replace-lines F A:B [NEW] replaces an inclusive line range, 1-based
greppy insert-lines F N [NEW] inserts after line N; 0 is the top of the file
greppy delete S / greppy delete-lines F A:B removes a definition or a line range
greppy write PATH [NEW] creates or overwrites a file
greppy rename S NAME renames a definition and every reference resolved in the graph
greppy patch [DIFF] applies a unified diff to existing files, all or nothing; you create new files with greppy write
greppy undo [ID] reverts the latest change or a named one

When NEW or DIFF is missing, the command reads from stdin. Every edit command takes --dry-run, --verify and --json. --verify checks syntax and build locally. With GREPPY_VERIFY_TEST_COMMAND, your test command also runs through bash-smart; if it fails, the edit ends with exit code 17 and stays applied, and greppy undo reverts it.

Run

Command Does
greppy bash-smart [-e REGEX] -- CMD … runs CMD with the same exit code and returns a verdict plus error and warning blocks; -e lifts matching lines into the answer
greppy PATTERN [FILE …], greppy -rn … byte-exact real grep
greppy rg … ripgrep: the real rg when it is installed, otherwise the common flags through grep or a clear refusal

Index, health and cache

Command Does
greppy index [PATH] builds or refreshes the graph and the meaning index
greppy index status --json readiness: ready when the command exits 0 and healthy and embedding_complete are true
greppy index recover [PATH] restores a recoverable index snapshot (0.4.1)
greppy index --agent-worktree prepares the worktree and the immutable Base the built-in agent uses
greppy stats files, nodes by kind, edges by type and the totals
greppy diagnostics [--json] schema, integrity, workspace state, graph statistics and completeness per language
greppy doctor [--json] end-to-end check of the active index and the inference backend
greppy cache status [--json] managed stores, models, quota, locks and unmanaged paths
greppy cache gc [--dry-run] [--json] runs the TTL/LRU cleanup now
greppy cache clear --root DIR --yes / --all --yes removes a worktree's store together with the repository's shared agent Bases, or every verified cache object; locked stores stay in place
greppy trial … a local comparison without and with greppy on your repository, run with Pi; prints a greppy.project-trial.v1 JSON record

greppy trial needs --question, --check who-calls, --symbol, --expect (repeatable), --runner pi, --provider and --model. It also takes --forbid (repeatable) and --timeout-seconds N (default 300).

Built-in agent (beta)

Command Does
greppy -p "TASK" [--model M] headless agent for one task; returns a proposal as a ref under refs/greppy/agent/
greppy agent ["TASK"] interactive full-screen session in the terminal (0.4.1)
greppy agent apply REF applies a proposal to exactly the captured baseline (0.4.1)
greppy agent sessions list|show|tail|path reads saved sessions; list --all-projects, show --full, tail --follow --lines N (default 40) (0.4.1)
greppy agent serve [TASK] [--model M] hosts a headless session on a per-user Unix socket; --idle-timeout-secs N, --continue, --resume ID (0.4.1)
greppy agent status|send|attach|interrupt|quit ID drives a running session from another shell; send --wait, attach --since-start (0.4.1)
greppy agent stdio [--model M] speaks the Agent Client Protocol over stdin/stdout for a host application; --max-turns N (0.4.1)
greppy prompt [--mode one-shot|interactive|serve|acp|external] [--json] prints the embedded prompt with version and SHA-256; --external prints the contract for external agents (0.4.1)
greppy workspace setup|doctor|status|gc the optional copy-on-write provider for acceleration (0.4.1)

-p takes the flags --model M, --endpoint URL (default http://127.0.0.1:8317), --max-turns N, --deadline-secs N, --apply, --diff, --keep-worktree, --no-sandbox, --skip-selfcheck, --continue, --resume ID and --json. See Built-in agent.

Browser tool (beta, 0.4.1)

Group Commands
Navigate greppy web open URL, goto URL, back, forward, reload, do STEP :: STEP …
See observe, find, match, extract, inspect, dom html, dom stats, screenshot, events, console, network, trace start|stop
Act click, fill, type, clear, select, check, uncheck, press, hover, scroll, upload, wait, assert
Sessions session create|list|close, tab new|list|switch|close, runtime status|stop|restart, status, doctor
Scripts js, pw, run --script-file F or --script-stdin, script save|list|show|rm|run, endpoint
Results read URL, search QUERY, research QUERY, artifact list|show|path|export, artifacts, result next CURSOR, cancel, heartbeat

All browser commands start with greppy web. See Browser tool.

Global flags

These flags work before or after the subcommand:

Flag Effect
--root DIR works on another repository
--device auto|cpu|metal|cuda[:INDEX] inference backend for both embedded models (or GREPPY_DEVICE); auto picks Metal on the Mac and CUDA on Linux; an explicitly chosen backend that is missing ends with a diagnostic and exit code 73
--no-gpu older spelling of --device cpu
--limit N (alias --max), --offset N at most N results, starting at row N
--max-bytes N fixed stdout budget for navigation, search and read output
--diagnostics brings back the full diagnostics envelope in --json
-h, --help / -V, --version help / version

Commands whose output supports them also take --json (data with exact counts), --code (source at each result), --all (lifts the result cap) and --path P (restricts results to this path, repeatable). greppy reports an unknown option with note: ignoring unknown option and keeps working.

Exit codes

Code Meaning
0 answered, including an empty answer that says so (no callers); search family: a hit
1 search family and grep form: no hit; also a symbol or file that does not exist, or an ambiguous name whose definitions greppy lists
10 undo: nothing to revert
12 replace-span: the file has changed since the handle; nothing is written
13 replace-text: OLD does not occur; nothing is written
17 --verify: the test command from GREPPY_VERIFY_TEST_COMMAND fails; the edit stays applied (0.4.1)
73 doctor: index or inference backend not healthy, including an explicitly chosen --device that is missing; diagnostics: the output counts incomplete language providers (incomplete_providers)
75 temporary: the index is still being prepared or another process holds the builder lock; the message names the condition for the next attempt 
$ greppy who-calls ZzzNoSuchSymbol; echo "exit $?"
no symbol `ZzzNoSuchSymbol`
exit 1
$ greppy replace-text serde/src/lib.rs "ZzzNoSuchText" "x"; echo "exit $?"
OLD occurs 0 times — nothing written
exit 13

grep invocations return the exit codes of grep. The agent and the browser tool have their own codes, described on their pages.

Environment variables

Variable Effect
GREPPY_STORE_DIR absolute directory for the index stores (under GREPPY_STORE_DIR/workspaces/); use the same value for index, status, queries and edits
GREPPY_SHARED_INFERENCE_ROOT shared location for models and inference caches; without it, they follow GREPPY_STORE_DIR (0.4.1)
GREPPY_STORE_TTL_DAYS age limit of the workspace cache (default 14); 0 turns the age limit off, the size quota stays
GREPPY_STORE_MAX_GIB size quota of the cache in GiB (default 10)
GREPPY_DEVICE inference backend, like --device
GREPPY_VERIFY_TEST_COMMAND test command that --verify runs through bash-smart (0.4.1)
GREPPY_ENDPOINT, GREPPY_MODEL, GREPPY_API_KEY the agent's gateway URL (default http://127.0.0.1:8317), model ID and gateway key
GREPPY_DEADLINE_SECS, GREPPY_NO_SANDBOX, GREPPY_SKIP_SELFCHECK the agent's time budget, sandbox off, self-check off

TMPDIR controls temporary files, not the index location. XDG_CACHE_HOME does not choose the index location. greppy cache status --json shows the effective age limit (ttl_secs) and quota (quota_bytes).