# Riferimento CLI

Greph include quattro eseguibili. Tutti e quattro condividono lo stesso motore; cambia solo l'interfaccia che espongono.

| Binario | Scopo |
|---|---|
| `greph` | Ricerca testuale nativa, ricerca AST e riscrittura AST |
| `greph-index` | Indice testuale riscaldato, indice di fatti AST e ricerca AST memorizzata nella cache |
| `rg` | Wrapper di compatibilità in stile ripgrep |
| `sg` | Wrapper di compatibilità in stile ast-grep |

Tutti i percorsi negli esempi usano `./vendor/bin/<binary>`, che funziona con Greph 0.2.3 o versioni successive installate come dipendenza. Sostituisci con `./bin/<binary>` se stai lavorando da un clone del repository.

---

## `greph`

Ricerca testuale nativa, ricerca AST e riscrittura AST.

```bash
greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]
```

Se si omette un percorso, la ricerca viene eseguita nella directory corrente.

### Modalità testuale

Modalità predefinita. I pattern sono espressioni regolari PCRE2, a meno che non sia impostato `-F`.

```bash
# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src
```

Il formato di output corrisponde a `grep -rn`:

```text
src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...
```

### Modalità AST

Si attiva con `-p`. I pattern sono scritti come normale PHP con metavariabili `$VAR` e `$$$VARIADIC`. Per la grammatica completa dei pattern, consulta [Modalità / Ricerca AST](https://greph.inline0.dev/it/docs/modes/ast).

```bash
./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
```

### Modalità di riscrittura

Si attiva combinando `-p` con `-r`. Il modello di sostituzione usa le stesse metavariabili del pattern di ricerca; i nodi acquisiti vengono inseriti usando il nome.

```bash
# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

### Opzioni

| Opzione | Significato |
|---|---|
| `-F` | Ricerca per stringa esatta (senza espressioni regolari) |
| `-i` | Ricerca senza distinzione tra maiuscole e minuscole |
| `-w` | Corrispondenza di parole intere |
| `-v` | Inverti la corrispondenza |
| `-c` | Conta le corrispondenze per file |
| `-l` | Elenca solo i percorsi dei file corrispondenti |
| `-L` | Elenca solo i percorsi dei file non corrispondenti |
| `-h` | Sopprimi i prefissi dei nomi file in modalità testuale |
| `-H` | Stampa sempre i prefissi dei nomi file in modalità testuale |
| `-n` | Mostra i numeri di riga (predefinito: attivo) |
| `-A N` | Mostra N righe dopo ogni corrispondenza |
| `-B N` | Mostra N righe prima di ogni corrispondenza |
| `-C N` | Mostra N righe di contesto prima e dopo ogni corrispondenza |
| `-m N` | Interrompi dopo N corrispondenze per file |
| `-j N` | Usa N worker paralleli |
| `-p PATTERN` | Pattern di ricerca AST |
| `-r TEMPLATE` | Modello di riscrittura AST (richiede `-p`) |
| `--glob GLOB` | Includi solo i file il cui percorso corrisponde a GLOB |
| `--type NAME` | Includi un alias di tipo file (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Escludi un alias di tipo file |
| `--lang NAME` | Linguaggio AST. Predefinito: `php` |
| `--json` | Genera output JSON |
| `--no-ignore` | Ignora le regole `.gitignore` e `.grephignore` |
| `--hidden` | Includi i file nascosti |
| `--dry-run` | Mostra le riscritture senza scrivere i file |
| `--interactive` | Conferma ogni file riscritto |
| `--help` | Mostra la guida rapida inline |

---

## `greph-index`

Indice testuale riscaldato, indice di fatti AST e ricerca AST memorizzata nella cache.

```bash
greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]
```

### Indice testuale

```bash
# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin
```

L'indice testuale è un archivio riscaldato di trigrammi e posting degli identificatori. Per impostazione predefinita si trova in `.greph-index/` nella root indicizzata.

### Set di indici

I set di indici trasformano i flussi di lavoro ripetuti con più indici in un manifest con nome:

```bash
./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
```

Il file manifest predefinito è `.greph-index-set.json`. Ogni voce punta a una root, una modalità e un profilo del ciclo di vita. `set build` e `set refresh` operano sulle voci abilitate; `set search` si applica alle voci selezionate ed elimina le corrispondenze sovrapposte.

### Indice di fatti AST

```bash
./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin
```

L'indice di fatti AST estrae fatti a livello di nodo (chiamate, istanziazioni, classi, metodi) in un archivio interrogabile. Le ricerche avvengono tramite O(log n) sulla chiave del fatto, quindi vengono verificate sul codice sorgente. Per impostazione predefinita, è archiviato in `.greph-ast-index/`.

### Cache AST

```bash
./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src
```

La cache AST archivia gli alberi analizzati su disco, così le ricerche possono saltare del tutto il parser. Per impostazione predefinita, è archiviata in `.greph-ast-cache/`.

### Opzioni

Le opzioni di ricerca testuale corrispondono al set di flag `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Flag aggiuntivi:

| Opzione | Significato |
|---|---|
| `--index-dir DIR` | Usa una directory di indice riscaldato non predefinita. Ripetibile per ricerche e statistiche su più indici. |
| `--lifecycle PROFILE` | Criterio di compilazione: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Soglia dei file per l'aggiornamento opportunistico |
| `--auto-refresh-max-bytes N` | Soglia dei byte per l'aggiornamento opportunistico |
| `--manifest FILE` | Carica un manifest di set di indici. Predefinito: `.greph-index-set.json` |
| `--mode MODE` | Limita le operazioni sui set a `text`, `ast-index` o `ast-cache` |
| `--index NAME` | Limita le operazioni sui set a una voce del manifest specificata. Ripetibile. |
| `--show-index-origin` | Aggiunge ai risultati delle ricerche su più indici o sui set il nome della voce di indice corrispondente |
| `--trace-plan` | Invia la diagnostica del planner riscaldato a `stderr` |
| `--dry-refresh` | In `stats`, mostra cosa farebbe una ricerca riscaldata senza modificare nulla |
| `--lang NAME` | Linguaggio AST per le ricerche `ast-index` / `ast-cache`. Predefinito: `php` |
| `-j N`, `--jobs N` | Worker per le scansioni AST |
| `-l`, `--files-with-matches` | Elenca solo i percorsi dei file corrispondenti (modalità AST) |
| `--strict-parse` | Genera errori di analisi invece di ignorarli |
| `--fallback MODE` | Comportamento in assenza di indice: `fail` (predefinito) o `scan` |
| `--help` | Mostra la guida rapida inline |

---

## `rg`

Wrapper di compatibilità in stile ripgrep. Supporta i flag ripgrep più usati. Le funzionalità verificate sono elencate nella [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix).

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

### Esempi

```bash
./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .
```

### Opzioni supportate

| Opzione | Significato |
|---|---|
| `-F`, `--fixed-strings` | Ricerca per stringa esatta |
| `-i`, `--ignore-case` | Ricerca senza distinzione tra maiuscole e minuscole |
| `-w`, `--word-regexp` | Ricerca di parole intere |
| `-v`, `--invert-match` | Inverte le corrispondenze |
| `-c`, `--count` | Conta le righe corrispondenti |
| `-l`, `--files-with-matches` | Elenca i file corrispondenti |
| `--files-without-match` | Elenca i file non corrispondenti |
| `-I`, `--no-filename` | Sopprime i prefissi dei nomi file |
| `-H`, `--with-filename` | Stampa sempre i prefissi dei nomi file |
| `-n`, `--line-number` | Mostra i numeri di riga |
| `-A N`, `--after-context N` | Mostra N righe dopo ogni corrispondenza |
| `-B N`, `--before-context N` | Mostra N righe prima di ogni corrispondenza |
| `-C N`, `--context N` | Mostra N righe prima e dopo ogni corrispondenza |
| `-m N`, `--max-count N` | Interrompe dopo N corrispondenze per file |
| `-j N`, `--threads N` | Usa N worker paralleli |
| `-e P`, `--regexp P` | Pattern di ricerca |
| `-L`, `--follow` | Segue i collegamenti simbolici |
| `--glob GLOB` | Includi solo i file il cui percorso corrisponde a GLOB |
| `--type NAME` | Includi un tipo di file |
| `--type-not NAME` | Escludi un tipo di file |
| `--json` | Genera eventi ripgrep in stile JSON |
| `--no-ignore` | Ignora le regole `.gitignore` e `.grephignore` |
| `--hidden` | Includi i file nascosti |
| `--files` | Elenca i file candidati invece di eseguire la ricerca |
| `--help` | Mostra la guida rapida inline |

---

## `sg`

Wrapper di compatibilità in stile ast-grep. Supporta i flag ast-grep più usati. Le funzionalità verificate sono elencate nella [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix).

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` è il verbo canonico di ast-grep. `scan` e `rewrite` sono alias disponibili solo nei wrapper, che riproducono l'uso comune. Funziona anche un'invocazione senza argomenti (`sg --pattern ... .`) per una ricerca singola.

### Esempi

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php
```

### Opzioni supportate

| Opzione | Significato |
|---|---|
| `-p`, `--pattern PATTERN` | Pattern AST |
| `-r`, `--rewrite TEMPLATE` | Modello di riscrittura |
| `-l`, `--lang NAME` | Linguaggio AST. Predefinito: `php` |
| `-j`, `--threads N` | Usa N worker paralleli |
| `-i`, `--interactive` | Conferma ogni riscrittura |
| `-U`, `--update-all` | Applica le riscritture senza conferma |
| `--files-with-matches` | Stampa solo i percorsi dei file con corrispondenze |
| `--json[=STYLE]` | Genera output JSON. STILE = `pretty`, `stream` o `compact` |
| `--no-ignore [MODE]` | Ignora le regole di esclusione del repository |
| `--hidden` | Includi i file nascosti |
| `--glob GLOB`, `--globs GLOB` | Includi solo i file il cui percorso corrisponde a GLOB |
| `--type NAME` | Includi un tipo di file |
| `--type-not NAME` | Escludi un tipo di file |
| `--dry-run` | Anteprima delle riscritture senza scrivere i file |
| `--help` | Mostra la guida rapida inline |

---

## Codici di uscita

Greph segue le convenzioni di grep / ripgrep:

| Codice | Significato |
|---|---|
| `0` | È stata trovata almeno una corrispondenza (oppure, per le riscritture, è stato modificato almeno un file) |
| `1` | Nessuna corrispondenza trovata |
| `2` | Errore di utilizzo o di esecuzione (argomenti non validi, indice mancante, errore di analisi in modalità `--strict-parse`) |