# Referência de CLI

Greph inclui quatro executáveis. Os quatro compartilham o mesmo mecanismo; a diferença está na interface que oferecem.

| Binário | Finalidade |
|---|---|
| `greph` | Pesquisa nativa de texto, pesquisa AST e reescrita AST |
| `greph-index` | Índice de texto aquecido, índice de fatos AST e pesquisa AST em cache |
| `rg` | Wrapper de compatibilidade no estilo ripgrep |
| `sg` | Wrapper de compatibilidade no estilo ast-grep |

Todos os caminhos nos exemplos usam `./vendor/bin/<binary>`, que funciona com Greph 0.2.3 ou posterior instalado como dependência. Substitua por `./bin/<binary>` se estiver trabalhando a partir de um clone do repositório.

---

## `greph`

Pesquisa nativa de texto, pesquisa AST e reescrita AST.

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

Se um caminho for omitido, a pesquisa será feita no diretório atual.

### Modo de texto

Modo padrão. Os padrões são expressões regulares PCRE2, a menos que `-F` esteja definido.

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

O formato de saída corresponde ao de `grep -rn`:

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

### Modo AST

Ativado por `-p`. Os padrões são escritos como PHP comuns, com metavariáveis `$VAR` e `$$$VARIADIC`. Consulte [Modos / Pesquisa AST](https://greph.inline0.dev/pt/docs/modes/ast) para ver a gramática completa dos padrões.

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

Ativado ao combinar `-p` com `-r`. O modelo de substituição usa as mesmas metavariáveis do padrão de pesquisa; os nós capturados são inseridos pelo 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
```

### Opções

| Sinalizador | Significado |
|---|---|
| `-F` | Pesquisa por cadeia fixa (sem regex) |
| `-i` | Correspondência sem distinção entre maiúsculas e minúsculas |
| `-w` | Correspondência de palavra inteira |
| `-v` | Inverter correspondência |
| `-c` | Contar correspondências por arquivo |
| `-l` | Listar somente os caminhos dos arquivos correspondentes |
| `-L` | Listar somente os caminhos dos arquivos sem correspondências |
| `-h` | Omitir prefixos de nome de arquivo no modo de texto |
| `-H` | Sempre exibir prefixos de nome de arquivo no modo de texto |
| `-n` | Exibir números de linha (padrão: ativado) |
| `-A N` | Exibir N linhas após cada correspondência |
| `-B N` | Exibir N linhas antes de cada correspondência |
| `-C N` | Exibir N linhas de contexto antes e depois de cada correspondência |
| `-m N` | Parar após N correspondências por arquivo |
| `-j N` | Usar N workers paralelos |
| `-p PATTERN` | Padrão de pesquisa AST |
| `-r TEMPLATE` | Modelo de reescrita AST (requer `-p`) |
| `--glob GLOB` | Incluir somente arquivos cujos caminhos correspondam a GLOB |
| `--type NAME` | Incluir um alias de tipo de arquivo (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Excluir um alias de tipo de arquivo |
| `--lang NAME` | Linguagem AST. Padrão: `php` |
| `--json` | Emitir saída JSON |
| `--no-ignore` | Ignorar as regras `.gitignore` e `.grephignore` |
| `--hidden` | Incluir arquivos ocultos |
| `--dry-run` | Exibir reescritas sem gravar os arquivos |
| `--interactive` | Confirmar a reescrita de cada arquivo |
| `--help` | Exibir ajuda de uso inline |

---

## `greph-index`

Índice de texto aquecido, índice de fatos AST e pesquisa AST em 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...]
```

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

O índice de texto é um armazenamento aquecido de trigramas e ocorrências de identificadores. Por padrão, ele fica em `.greph-index/` na raiz indexada.

### Conjuntos de índices

Os conjuntos de índices transformam fluxos de trabalho repetidos com vários índices em um manifesto nomeado:

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

O arquivo de manifesto padrão é `.greph-index-set.json`. Cada entrada aponta para uma raiz, um modo e um perfil de ciclo de vida. `set build` e `set refresh` operam nas entradas ativadas; `set search` distribui a pesquisa pelas entradas selecionadas e elimina correspondências sobrepostas.

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

O índice de fatos AST extrai fatos no nível dos nós (chamadas, instanciações, classes, métodos) para um armazenamento consultável. As consultas fazem O(log n) na chave do fato e, em seguida, são verificadas em relação ao código-fonte. Por padrão, fica armazenado em `.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
```

O cache AST armazena árvores analisadas em disco para que as pesquisas ignorem completamente o analisador. Por padrão, fica armazenado em `.greph-ast-cache/`.

### Opções

As opções de pesquisa de texto correspondem ao conjunto de sinalizadores `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Sinalizadores adicionais:

| Sinalizador | Significado |
|---|---|
| `--index-dir DIR` | Usar um diretório de índice aquecido que não seja o padrão. Repetível para pesquisa e estatísticas com vários índices. |
| `--lifecycle PROFILE` | Política de compilação: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Limite de arquivos para atualização oportunista |
| `--auto-refresh-max-bytes N` | Limite de bytes para atualização oportunista |
| `--manifest FILE` | Carregar um manifesto de conjunto de índices. Padrão: `.greph-index-set.json` |
| `--mode MODE` | Restringir as operações do conjunto a `text`, `ast-index` ou `ast-cache` |
| `--index NAME` | Restringir as operações do conjunto a uma entrada nomeada do manifesto. Repetível. |
| `--show-index-origin` | Prefixar a saída aquecida de vários índices ou conjuntos com o nome da entrada de índice correspondente |
| `--trace-plan` | Emitir diagnósticos do planejador aquecido em `stderr` |
| `--dry-refresh` | Em `stats`, informar o que uma pesquisa aquecida faria sem alterar nada |
| `--lang NAME` | Linguagem AST para pesquisas `ast-index` / `ast-cache`. Padrão: `php` |
| `-j N`, `--jobs N` | Workers para varreduras AST |
| `-l`, `--files-with-matches` | Listar somente os caminhos dos arquivos correspondentes (modo AST) |
| `--strict-parse` | Falhar em caso de erros de análise em vez de ignorá-los |
| `--fallback MODE` | Comportamento quando não há índice: `fail` (padrão) ou `scan` |
| `--help` | Exibir ajuda de uso inline |

---

## `rg`

Wrapper de compatibilidade no estilo ripgrep. Compatível com os sinalizadores ripgrep mais usados. A interface verificada está publicada na [matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix).

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

### Exemplos

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

### Opções compatíveis

| Sinalizador | Significado |
|---|---|
| `-F`, `--fixed-strings` | Pesquisa por cadeia fixa |
| `-i`, `--ignore-case` | Pesquisa sem distinção entre maiúsculas e minúsculas |
| `-w`, `--word-regexp` | Pesquisa por palavra inteira |
| `-v`, `--invert-match` | Inverter correspondências |
| `-c`, `--count` | Contar linhas correspondentes |
| `-l`, `--files-with-matches` | Listar arquivos correspondentes |
| `--files-without-match` | Listar arquivos sem correspondências |
| `-I`, `--no-filename` | Omitir prefixos de nome de arquivo |
| `-H`, `--with-filename` | Sempre exibir prefixos de nome de arquivo |
| `-n`, `--line-number` | Exibir números de linha |
| `-A N`, `--after-context N` | Exibir N linhas após cada correspondência |
| `-B N`, `--before-context N` | Exibir N linhas antes de cada correspondência |
| `-C N`, `--context N` | Exibir N linhas antes e depois de cada correspondência |
| `-m N`, `--max-count N` | Parar após N correspondências por arquivo |
| `-j N`, `--threads N` | Usar N workers paralelos |
| `-e P`, `--regexp P` | Padrão de pesquisa |
| `-L`, `--follow` | Seguir links simbólicos |
| `--glob GLOB` | Incluir somente arquivos cujos caminhos correspondam a GLOB |
| `--type NAME` | Incluir um tipo de arquivo |
| `--type-not NAME` | Excluir um tipo de arquivo |
| `--json` | Emitir eventos ripgrep no estilo JSON |
| `--no-ignore` | Ignorar as regras `.gitignore` e `.grephignore` |
| `--hidden` | Incluir arquivos ocultos |
| `--files` | Listar arquivos candidatos em vez de pesquisar |
| `--help` | Exibir ajuda de uso inline |

---

## `sg`

Wrapper de compatibilidade no estilo ast-grep. Compatível com os sinalizadores ast-grep mais usados. A interface verificada está publicada na [matriz de recursos](https://greph.inline0.dev/pt/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` é o verbo canônico de ast-grep. `scan` e `rewrite` são aliases exclusivos do wrapper que refletem o uso comum. Uma chamada sem argumentos também funciona como pesquisa pontual (`sg --pattern ... .`).

### Exemplos

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

### Opções compatíveis

| Sinalizador | Significado |
|---|---|
| `-p`, `--pattern PATTERN` | Padrão AST |
| `-r`, `--rewrite TEMPLATE` | Modelo de reescrita |
| `-l`, `--lang NAME` | Linguagem AST. Padrão: `php` |
| `-j`, `--threads N` | Usar N workers paralelos |
| `-i`, `--interactive` | Confirmar cada reescrita |
| `-U`, `--update-all` | Aplicar reescritas sem confirmação |
| `--files-with-matches` | Exibir somente os caminhos dos arquivos com correspondências |
| `--json[=STYLE]` | Emitir saída JSON. STYLE = `pretty`, `stream` ou `compact` |
| `--no-ignore [MODE]` | Ignorar as regras de exclusão do repositório |
| `--hidden` | Incluir arquivos ocultos |
| `--glob GLOB`, `--globs GLOB` | Incluir somente arquivos cujos caminhos correspondam a GLOB |
| `--type NAME` | Incluir um tipo de arquivo |
| `--type-not NAME` | Excluir um tipo de arquivo |
| `--dry-run` | Visualizar reescritas sem gravar os arquivos |
| `--help` | Exibir ajuda de uso inline |

---

## Códigos de saída

Greph segue as convenções de grep / ripgrep:

| Código | Significado |
|---|---|
| `0` | Foi encontrada pelo menos uma correspondência (ou, para reescritas, pelo menos um arquivo foi alterado) |
| `1` | Nenhuma correspondência encontrada |
| `2` | Erro de uso ou falha em tempo de execução (argumentos inválidos, índice ausente, erro de análise no modo `--strict-parse`) |