# Referencia de CLI

Greph incluye cuatro ejecutables. Los cuatro comparten el mismo motor; se diferencian en la interfaz que ofrecen.

| Binario | Propósito |
|---|---|
| `greph` | Búsqueda de texto nativa, búsqueda AST y reescritura AST |
| `greph-index` | Índice de texto precargado, índice de hechos AST y búsqueda AST en caché |
| `rg` | Envoltorio de compatibilidad al estilo de ripgrep |
| `sg` | Envoltorio de compatibilidad al estilo de ast-grep |

Todas las rutas de los ejemplos usan `./vendor/bin/<binary>`, que funciona con Greph 0.2.3 o versiones posteriores instaladas como dependencia. Sustituya `./bin/<binary>` si trabaja desde un clon del repositorio.

---

## `greph`

Búsqueda de texto nativa, búsqueda AST y reescritura AST.

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

Si se omite una ruta, se busca en el directorio actual.

### Modo de texto

Modo predeterminado. Los patrones son expresiones regulares PCRE2, salvo que se establezca `-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
```

El formato de salida coincide con el de `grep -rn`:

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

### Modo AST

Se activa con `-p`. Los patrones se escriben como PHP normales, con met variables `$VAR` y `$$$VARIADIC`. Consulte [Modos / Búsqueda AST](https://greph.inline0.dev/es/docs/modes/ast) para ver la gramática completa de los patrones.

```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
```

### Modo de reescritura

Se activa al combinar `-p` con `-r`. La plantilla de reemplazo usa los mismos met variables que el patrón de búsqueda; los nodos capturados se insertan por nombre.

```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
```

### Opciones

| Opción | Significado |
|---|---|
| `-F` | Búsqueda de cadenas literales (sin expresiones regulares) |
| `-i` | Coincidencia sin distinguir mayúsculas y minúsculas |
| `-w` | Coincidencia de palabras completas |
| `-v` | Invertir coincidencia |
| `-c` | Contar coincidencias por archivo |
| `-l` | Mostrar solo las rutas de archivos con coincidencias |
| `-L` | Mostrar solo las rutas de archivos sin coincidencias |
| `-h` | Suprimir prefijos de nombre de archivo en modo de texto |
| `-H` | Mostrar siempre prefijos de nombre de archivo en modo de texto |
| `-n` | Mostrar números de línea (activado de forma predeterminada) |
| `-A N` | Mostrar N líneas después de cada coincidencia |
| `-B N` | Mostrar N líneas antes de cada coincidencia |
| `-C N` | Mostrar N líneas de contexto antes y después de cada coincidencia |
| `-m N` | Detenerse tras N coincidencias por archivo |
| `-j N` | Usar N procesos de trabajo en paralelo |
| `-p PATTERN` | Patrón de búsqueda AST |
| `-r TEMPLATE` | Plantilla de reescritura AST (requiere `-p`) |
| `--glob GLOB` | Incluir solo archivos cuyas rutas coincidan con GLOB |
| `--type NAME` | Incluir un alias de tipo de archivo (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Excluir un alias de tipo de archivo |
| `--lang NAME` | Lenguaje AST. Predeterminado: `php` |
| `--json` | Emitir salida JSON |
| `--no-ignore` | Ignorar las reglas de `.gitignore` y `.grephignore` |
| `--hidden` | Incluir archivos ocultos |
| `--dry-run` | Mostrar reescrituras sin escribir los archivos |
| `--interactive` | Confirmar cada archivo reescrito |
| `--help` | Mostrar ayuda de uso integrada |

---

## `greph-index`

Índice de texto precargado, índice de hechos AST y búsqueda AST en caché.

```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...]
```

### Índice de texto

```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
```

El índice de texto es un almacén precargado de trigramas y publicaciones de identificadores. De forma predeterminada, se encuentra en `.greph-index/` dentro de la raíz indexada.

### Conjuntos de índices

Los conjuntos de índices convierten los flujos de trabajo repetidos con varios índices en un manifiesto con nombre:

```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)' .
```

El archivo de manifiesto predeterminado es `.greph-index-set.json`. Cada entrada apunta a una raíz, un modo y un perfil de ciclo de vida. `set build` y `set refresh` operan sobre las entradas habilitadas; `set search` se ejecuta en las entradas seleccionadas y elimina las coincidencias duplicadas.

### Índice de hechos 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
```

El índice de hechos AST extrae datos a nivel de nodo (llamadas, instanciaciones, clases y métodos) y los guarda en un almacén consultable. Las búsquedas usan O(log n) sobre la clave del hecho y luego se verifican con el código fuente. De forma predeterminada, se guarda en `.greph-ast-index/`.

### Caché 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 caché AST guarda los árboles analizados en el disco para que las búsquedas omitan por completo el analizador. De forma predeterminada, se guarda en `.greph-ast-cache/`.

### Opciones

Las opciones de búsqueda de texto coinciden con el conjunto de opciones `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Opciones adicionales:

| Opción | Significado |
|---|---|
| `--index-dir DIR` | Usar un directorio de índice precargado distinto del predeterminado. Repetible para búsquedas y estadísticas con varios índices. |
| `--lifecycle PROFILE` | Política de creación: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Umbral de archivos para la actualización oportunista |
| `--auto-refresh-max-bytes N` | Umbral de bytes para la actualización oportunista |
| `--manifest FILE` | Cargar un manifiesto de conjunto de índices. Predeterminado: `.greph-index-set.json` |
| `--mode MODE` | Limitar las operaciones del conjunto a `text`, `ast-index` o `ast-cache` |
| `--index NAME` | Limitar las operaciones del conjunto a una entrada de manifiesto con nombre. Repetible. |
| `--show-index-origin` | Anteponer a la salida de búsquedas precargadas con varios índices o conjuntos el nombre de la entrada de índice correspondiente |
| `--trace-plan` | Emitir diagnósticos del planificador precargado en `stderr` |
| `--dry-refresh` | En `stats`, informar de lo que haría una búsqueda precargada sin modificar nada |
| `--lang NAME` | Lenguaje AST para búsquedas `ast-index` / `ast-cache`. Predeterminado: `php` |
| `-j N`, `--jobs N` | Procesos de trabajo para análisis AST |
| `-l`, `--files-with-matches` | Mostrar solo las rutas de archivos con coincidencias (modo AST) |
| `--strict-parse` | Fallar ante errores de análisis en vez de omitirlos |
| `--fallback MODE` | Comportamiento cuando falta el índice: `fail` (predeterminado) o `scan` |
| `--help` | Mostrar ayuda de uso integrada |

---

## `rg`

Envoltorio de compatibilidad al estilo de ripgrep. Admite las opciones ripgrep más utilizadas. La compatibilidad verificada se publica en la [matriz de funciones](https://greph.inline0.dev/es/docs/advanced/feature-matrix).

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

### Ejemplos

```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" .
```

### Opciones admitidas

| Opción | Significado |
|---|---|
| `-F`, `--fixed-strings` | Búsqueda de cadenas literales |
| `-i`, `--ignore-case` | Búsqueda sin distinguir mayúsculas y minúsculas |
| `-w`, `--word-regexp` | Búsqueda de palabras completas |
| `-v`, `--invert-match` | Invertir coincidencias |
| `-c`, `--count` | Contar líneas coincidentes |
| `-l`, `--files-with-matches` | Mostrar archivos con coincidencias |
| `--files-without-match` | Mostrar archivos sin coincidencias |
| `-I`, `--no-filename` | Suprimir prefijos de nombre de archivo |
| `-H`, `--with-filename` | Mostrar siempre prefijos de nombre de archivo |
| `-n`, `--line-number` | Mostrar números de línea |
| `-A N`, `--after-context N` | Mostrar N líneas después de cada coincidencia |
| `-B N`, `--before-context N` | Mostrar N líneas antes de cada coincidencia |
| `-C N`, `--context N` | Mostrar N líneas antes y después de cada coincidencia |
| `-m N`, `--max-count N` | Detenerse tras N coincidencias por archivo |
| `-j N`, `--threads N` | Usar N procesos de trabajo en paralelo |
| `-e P`, `--regexp P` | Patrón de búsqueda |
| `-L`, `--follow` | Seguir enlaces simbólicos |
| `--glob GLOB` | Incluir solo archivos cuyas rutas coincidan con GLOB |
| `--type NAME` | Incluir un tipo de archivo |
| `--type-not NAME` | Excluir un tipo de archivo |
| `--json` | Emitir eventos ripgrep JSON |
| `--no-ignore` | Ignorar las reglas de `.gitignore` y `.grephignore` |
| `--hidden` | Incluir archivos ocultos |
| `--files` | Mostrar los archivos candidatos en lugar de buscarlos |
| `--help` | Mostrar ayuda de uso integrada |

---

## `sg`

Envoltorio de compatibilidad al estilo de ast-grep. Admite las opciones ast-grep más utilizadas. La compatibilidad verificada se publica en la [matriz de funciones](https://greph.inline0.dev/es/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` es el verbo canónico de ast-grep. `scan` y `rewrite` son alias exclusivos del envoltorio que reflejan el uso habitual. También funciona una invocación sin argumentos (`sg --pattern ... .`) para realizar una búsqueda puntual.

### Ejemplos

```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
```

### Opciones admitidas

| Opción | Significado |
|---|---|
| `-p`, `--pattern PATTERN` | Patrón AST |
| `-r`, `--rewrite TEMPLATE` | Plantilla de reescritura |
| `-l`, `--lang NAME` | Lenguaje AST. Predeterminado: `php` |
| `-j`, `--threads N` | Usar N procesos de trabajo en paralelo |
| `-i`, `--interactive` | Confirmar cada reescritura |
| `-U`, `--update-all` | Aplicar reescrituras sin confirmación |
| `--files-with-matches` | Mostrar solo las rutas de archivos con coincidencias |
| `--json[=STYLE]` | Emitir salida JSON. STYLE = `pretty`, `stream` o `compact` |
| `--no-ignore [MODE]` | Ignorar las reglas de exclusión del repositorio |
| `--hidden` | Incluir archivos ocultos |
| `--glob GLOB`, `--globs GLOB` | Incluir solo archivos cuyas rutas coincidan con GLOB |
| `--type NAME` | Incluir un tipo de archivo |
| `--type-not NAME` | Excluir un tipo de archivo |
| `--dry-run` | Previsualizar reescrituras sin escribir los archivos |
| `--help` | Mostrar ayuda de uso integrada |

---

## Códigos de salida

Greph sigue las convenciones de grep / ripgrep:

| Código | Significado |
|---|---|
| `0` | Se encontró al menos una coincidencia (o, en las reescrituras, se modificó al menos un archivo) |
| `1` | No se encontraron coincidencias |
| `2` | Error de uso o fallo en tiempo de ejecución (argumentos incorrectos, falta el índice, error de análisis en el modo `--strict-parse`) |