CLI-Referenz
Jeder Befehl arbeitet auf dem aktuellen Repository oder auf dem, das du mit --root DIR übergibst. Die erste strukturierte Abfrage baut den Index. Normale grep-Aufrufe gehen direkt an das System-grep: Ein erstes Wort, das kein greppy-Befehl ist, landet als Muster bei grep. greppy --help und greppy <befehl> --help zeigen die exakte Oberfläche deines installierten Binarys.
Den Symbolgraphen navigieren
| Befehl | Beantwortet |
|---|---|
greppy who-calls S [S …] |
jede Stelle, die S aufruft oder nutzt (eingehende CALLS- und USAGE-Kanten) |
greppy callees S [S …] |
die indexierten Definitionen, die S direkt aufruft, mit Fundstelle |
greppy brief S [S …] |
Doku-Satz, Signatur, eine Zeile pro Aufruf oder Verzweigung im Körper, dazu die Aufrufer; Structs, Enums und Traits erscheinen vollständig |
greppy impact S [S …] |
die transitive Reichweite mit Hop-Abstand; --direction incoming (Standard) oder outgoing, --depth N (Standard 6), --edge TYP |
greppy path --from A --to B |
jede Aufrufkette als Baum der Aufrufstellen; --edge CALLS|USAGE|TYPE_ASSIGN|IMPORTS (Standard CALLS) |
greppy where-am-i |
das Repository auf einen Blick: Layout mit Definitionen je Ordner, Sprachen, Einstiegspunkte, Test-Wurzeln |
greppy graph-locate DATEI:ZEILE |
das innerste Symbol, das eine Stelle umschließt (oder --file F --line N) |
greppy fan-in / greppy fan-out |
meistgerufene / am meisten rufende Symbole; --edge CALLS|USAGE|USES|TYPE_REF|IMPORTS (Standard CALLS) |
greppy trace --symbol S |
Aufrufgraph Schritt für Schritt; --direction outgoing|incoming (Standard outgoing), --edge CALLS|USES|TYPE_REF|IMPORTS (Standard CALLS), --depth N (Standard 4) |
greppy search-graph --name NAME |
strukturierte Suche nach Graphknoten |
Bei impact folgt die Richtung incoming ohne --edge allen Referenzkanten, outgoing folgt CALLS. - statt eines Symbols liest die Symbole aus der Pipe.
Suchen
| Befehl | Findet |
|---|---|
greppy search "WAS ES TUT" |
Definitionen nach Bedeutung, gerankt, bis zu acht Treffer |
greppy search-symbol NAME |
Definitionen, deren Name NAME enthält |
greppy search-pattern REGEX |
jede passende Quelltextzeile, auch in Kommentaren, Strings und Konfiguration, mit der umschließenden Definition; --fixed für wörtlichen Text |
greppy plus QUERY |
gemischtes Ranking aus Text-, Symbol-, Bedeutungs- und Graphsignalen; --k N (Standard 10), --explain |
greppy expand ID |
das Beleg-Paket, das ein vorheriges Ergebnis angeboten hat |
--kind function|method|class|struct|enum|trait schränkt search, search-symbol und search-pattern ein. Bei vielen Treffern zeigt search-pattern eine über die Dateien verteilte Stichprobe mit der Gesamtzahl; --all druckt jede Zeile.
Quelltext lesen
| Befehl | Liefert |
|---|---|
greppy read S [S …] |
Definitionen als Quelltext-Bytes, mit Doku und Attributen direkt darüber; --head M, --tail N |
greppy read-smart S [S …] |
Quelltext mit gefalteten verschachtelten Blöcken; --depth N (Standard 1) |
greppy read-file PFAD [PFAD …] |
Dateien in Seiten zu 400 Zeilen; --lines A:B, --all, --outline (Gliederung der indexierten Definitionen, 0.4.1) |
--handle druckt bei jedem Lesebefehl zusätzlich ein Edit-Handle für jeden ausgegebenen Abschnitt.
Transaktional editieren
| Befehl | Macht |
|---|---|
greppy replace S [NEW] |
ersetzt eine Definition; --body nur ihren Körper |
greppy replace-span H [NEW] |
ersetzt den Abschnitt, den ein Handle benennt; verweigert, wenn sich die Datei seitdem geändert hat |
greppy replace-text F OLD [NEW] |
ersetzt OLD, das genau einmal vorkommt; --expect N, --regex |
greppy replace-lines F A:B [NEW] |
ersetzt einen inklusiven Zeilenbereich, 1-basiert |
greppy insert-lines F N [NEW] |
fügt nach Zeile N ein; 0 ist der Dateianfang |
greppy delete S / greppy delete-lines F A:B |
entfernt eine Definition oder einen Zeilenbereich |
greppy write PFAD [NEW] |
legt eine Datei an oder überschreibt sie |
greppy rename S NAME |
benennt eine Definition und jede im Graphen aufgelöste Referenz um |
greppy patch [DIFF] |
wendet einen Unified Diff auf bestehende Dateien an, ganz oder gar nicht; neue Dateien legst du mit greppy write an |
greppy undo [ID] |
nimmt die letzte oder eine benannte Änderung zurück |
Fehlt NEW oder DIFF, liest der Befehl von stdin. Jeder Edit-Befehl nimmt --dry-run, --verify und --json. --verify prüft lokal Syntax und Build. Mit GREPPY_VERIFY_TEST_COMMAND läuft zusätzlich dein Testbefehl über bash-smart; schlägt er fehl, endet der Edit mit Exit-Code 17 und bleibt angewendet, greppy undo nimmt ihn zurück.
Ausführen
| Befehl | Macht |
|---|---|
greppy bash-smart [-e REGEX] -- CMD … |
führt CMD mit demselben Exit-Code aus und liefert ein Urteil plus Fehler- und Warnungsblöcke; -e hebt passende Zeilen in die Antwort |
greppy PATTERN [DATEI …], greppy -rn … |
byte-genaues echtes grep |
greppy rg … |
ripgrep: das echte rg, wenn es installiert ist, sonst die gängigen Flags über grep oder eine klare Absage |
Index, Zustand und Cache
| Befehl | Macht |
|---|---|
greppy index [PFAD] |
baut oder aktualisiert Graph und Bedeutungsindex |
greppy index status --json |
Bereitschaft: bereit, wenn der Befehl mit 0 endet und healthy sowie embedding_complete true sind |
greppy index recover [PFAD] |
stellt einen wiederherstellbaren Index-Snapshot wieder her (0.4.1) |
greppy index --agent-worktree |
bereitet den Worktree und die unveränderliche Base vor, die der eingebaute Agent nutzt |
greppy stats |
Dateien, Knoten nach Art, Kanten nach Typ und die Summen |
greppy diagnostics [--json] |
Schema, Integrität, Workspace-Zustand, Graphstatistik und Vollständigkeit je Sprache |
greppy doctor [--json] |
End-to-End-Check des aktiven Index und des Inferenz-Backends |
greppy cache status [--json] |
verwaltete Stores, Modelle, Quote, Locks und nicht verwaltete Pfade |
greppy cache gc [--dry-run] [--json] |
startet die TTL/LRU-Bereinigung sofort |
greppy cache clear --root DIR --yes / --all --yes |
entfernt den Store eines Worktrees samt den geteilten Agent-Bases des Repositorys, oder jedes verifizierte Cache-Objekt; gesperrte Stores bleiben stehen |
greppy trial … |
ein lokaler Vergleich ohne und mit greppy auf deinem Repository, ausgeführt mit Pi; druckt einen JSON-Datensatz greppy.project-trial.v1 |
greppy trial braucht --question, --check who-calls, --symbol, --expect (wiederholbar), --runner pi, --provider und --model; dazu --forbid (wiederholbar) und --timeout-seconds N (Standard 300).
Eingebauter Agent (beta)
| Befehl | Macht |
|---|---|
greppy -p "AUFGABE" [--model M] |
Agent für eine Aufgabe ohne Oberfläche; liefert einen Vorschlag als Ref unter refs/greppy/agent/ |
greppy agent ["AUFGABE"] |
interaktive Vollbild-Sitzung im Terminal (0.4.1) |
greppy agent apply REF |
wendet einen Vorschlag auf genau die erfasste Ausgangsbasis an (0.4.1) |
greppy agent sessions list|show|tail|path |
gespeicherte Sitzungen lesen; list --all-projects, show --full, tail --follow --lines N (Standard 40) (0.4.1) |
greppy agent serve [AUFGABE] [--model M] |
hostet eine Sitzung ohne Oberfläche auf einem Unix-Socket pro Benutzer; --idle-timeout-secs N, --continue, --resume ID (0.4.1) |
greppy agent status|send|attach|interrupt|quit ID |
steuert eine laufende Sitzung aus einer anderen Shell; send --wait, attach --since-start (0.4.1) |
greppy agent stdio [--model M] |
spricht das Agent Client Protocol über stdin/stdout für eine Host-Anwendung; --max-turns N (0.4.1) |
greppy prompt [--mode one-shot|interactive|serve|acp|external] [--json] |
gibt den eingebetteten Prompt mit Version und SHA-256 aus; --external den Vertrag für externe Agents (0.4.1) |
greppy workspace setup|doctor|status|gc |
der optionale Copy-on-Write-Provider zur Beschleunigung (0.4.1) |
-p nimmt die Flags --model M, --endpoint URL (Standard http://127.0.0.1:8317), --max-turns N, --deadline-secs N, --apply, --diff, --keep-worktree, --no-sandbox, --skip-selfcheck, --continue, --resume ID und --json. Siehe Eingebauter Agent.
Browser-Werkzeug (beta, 0.4.1)
| Gruppe | Befehle |
|---|---|
| Navigieren | greppy web open URL, goto URL, back, forward, reload, do STEP :: STEP … |
| Sehen | observe, find, match, extract, inspect, dom html, dom stats, screenshot, events, console, network, trace start|stop |
| Handeln | click, fill, type, clear, select, check, uncheck, press, hover, scroll, upload, wait, assert |
| Sitzungen | session create|list|close, tab new|list|switch|close, runtime status|stop|restart, status, doctor |
| Skripte | js, pw, run --script-file F oder --script-stdin, script save|list|show|rm|run, endpoint |
| Ergebnisse | read URL, search QUERY, research QUERY, artifact list|show|path|export, artifacts, result next CURSOR, cancel, heartbeat |
Alle Browser-Befehle beginnen mit greppy web. Siehe Browser-Werkzeug.
Globale Flags
Diese Flags gelten vor oder nach dem Unterbefehl:
| Flag | Wirkung |
|---|---|
--root DIR |
arbeitet auf einem anderen Repository |
--device auto|cpu|metal|cuda[:INDEX] |
Inferenz-Backend für beide eingebetteten Modelle (oder GREPPY_DEVICE); auto nimmt Metal auf dem Mac und CUDA unter Linux; ein ausdrücklich gewähltes Backend, das fehlt, endet mit einer Diagnose und Exit-Code 73 |
--no-gpu |
ältere Schreibweise für --device cpu |
--limit N (Alias --max), --offset N |
höchstens N Ergebnisse, ab Zeile N |
--max-bytes N |
festes stdout-Budget für Navigations-, Such- und Leseausgaben |
--diagnostics |
liefert in --json wieder den vollen Diagnose-Umschlag |
-h, --help / -V, --version |
Hilfe / Version |
Befehle, deren Ausgabe es hergibt, nehmen außerdem --json (Daten mit exakten Zahlen), --code (Quelltext an jedem Ergebnis), --all (hebt die Ergebnisgrenze auf) und --path P (nur Ergebnisse unter diesem Pfad, wiederholbar). Eine unbekannte Option meldet greppy mit note: ignoring unknown option und arbeitet weiter.
Exit-Codes
| Code | Bedeutung |
|---|---|
| 0 | beantwortet, auch eine leere Antwort, die das sagt (no callers); Suchfamilie: Treffer |
| 1 | Suchfamilie und grep-Form: kein Treffer; ebenso ein Symbol oder eine Datei, die es nicht gibt, oder ein mehrdeutiger Name, dessen Definitionen greppy auflistet |
| 10 | undo: nichts zum Zurücknehmen |
| 12 | replace-span: die Datei hat sich seit dem Handle geändert; nichts wird geschrieben |
| 13 | replace-text: OLD kommt nicht vor; nichts wird geschrieben |
| 17 | --verify: der Testbefehl aus GREPPY_VERIFY_TEST_COMMAND schlägt fehl; der Edit bleibt angewendet (0.4.1) |
| 73 | doctor: Index oder Inferenz-Backend nicht gesund, auch ein ausdrücklich gewähltes --device, das fehlt; diagnostics: die Ausgabe zählt unvollständige Sprach-Provider (incomplete_providers) |
| 75 | vorübergehend: der Index wird noch vorbereitet oder ein anderer Prozess hält den Builder-Lock; die Meldung nennt die Bedingung für den nächsten Versuch |
$ 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-Aufrufe liefern die Exit-Codes von grep. Der Agent und das Browser-Werkzeug haben eigene Codes, beschrieben auf ihren Seiten.
Umgebungsvariablen
| Variable | Wirkung |
|---|---|
GREPPY_STORE_DIR |
absolutes Verzeichnis für die Index-Stores (unter GREPPY_STORE_DIR/workspaces/); nimm denselben Wert für Index, Status, Abfragen und Edits |
GREPPY_SHARED_INFERENCE_ROOT |
gemeinsamer Ort für Modelle und Inferenz-Caches; ohne ihn folgen sie GREPPY_STORE_DIR (0.4.1) |
GREPPY_STORE_TTL_DAYS |
Altersgrenze des Workspace-Caches (Standard 14); 0 schaltet die Altersgrenze ab, die Größenquote bleibt |
GREPPY_STORE_MAX_GIB |
Größenquote des Caches in GiB (Standard 10) |
GREPPY_DEVICE |
Inferenz-Backend, wie --device |
GREPPY_VERIFY_TEST_COMMAND |
Testbefehl, den --verify über bash-smart ausführt (0.4.1) |
GREPPY_ENDPOINT, GREPPY_MODEL, GREPPY_API_KEY |
Gateway-URL des Agents (Standard http://127.0.0.1:8317), Modell-ID und Gateway-Schlüssel |
GREPPY_DEADLINE_SECS, GREPPY_NO_SANDBOX, GREPPY_SKIP_SELFCHECK |
Zeitbudget des Agents, Sandbox aus, Selbsttest aus |
TMPDIR steuert temporäre Dateien, nicht den Ort des Index. XDG_CACHE_HOME wählt den Index-Ort nicht. greppy cache status --json zeigt die wirksame Altersgrenze (ttl_secs) und Quote (quota_bytes).