# CLI 참조

Greph에는 네 가지 실행 파일이 포함되어 있습니다. 네 파일은 모두 같은 엔진을 공유하며, 노출하는 인터페이스가 다릅니다.

| 바이너리 | 용도 |
|---|---|
| `greph` | 네이티브 텍스트 검색, AST 검색 및 AST 재작성 |
| `greph-index` | 워밍된 텍스트 인덱스, AST 팩트 인덱스 및 캐시된 AST 검색 |
| `rg` | ripgrep 스타일 호환 래퍼 |
| `sg` | ast-grep 스타일 호환 래퍼 |

예제의 모든 경로는 `./vendor/bin/<binary>`을 사용하며, 이는 종속성으로 설치된 Greph 0.2.3 이상에서 작동합니다. 저장소를 복제한 디렉터리에서 작업하는 경우 `./bin/<binary>`으로 바꾸세요.

---

## `greph`

네이티브 텍스트 검색, AST 검색 및 AST 재작성입니다.

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

경로를 생략하면 현재 디렉터리를 검색합니다.

### 텍스트 모드

기본 모드입니다. `-F`을 설정하지 않으면 패턴은 PCRE2 정규식으로 처리됩니다.

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

출력 형식은 `grep -rn`과 일치합니다.

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

### AST 모드

`-p`으로 활성화됩니다. 패턴은 PHP에 `$VAR` 및 `$$$VARIADIC` 메타변수를 사용해 작성합니다. 전체 패턴 문법은 [모드 / AST 검색](https://greph.inline0.dev/ko/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
```

### 재작성 모드

`-p`과 `-r`을 함께 사용해 활성화됩니다. 대체 템플릿은 검색 패턴과 동일한 메타변수를 사용하며, 캡처된 노드는 이름으로 끼워 넣습니다.

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

### 옵션

| 플래그 | 의미 |
|---|---|
| `-F` | 고정 문자열 검색(정규식 사용 안 함) |
| `-i` | 대소문자를 구분하지 않고 일치 |
| `-w` | 전체 단어 일치 |
| `-v` | 일치 결과 반전 |
| `-c` | 파일별 일치 항목 수 계산 |
| `-l` | 일치하는 파일 경로만 나열 |
| `-L` | 일치하지 않는 파일 경로만 나열 |
| `-h` | 텍스트 모드에서 파일 이름 접두사 생략 |
| `-H` | 텍스트 모드에서 파일 이름 접두사 항상 출력 |
| `-n` | 줄 번호 표시(기본값: 켜짐) |
| `-A N` | 각 일치 항목 뒤의 N줄 표시 |
| `-B N` | 각 일치 항목 앞의 N줄 표시 |
| `-C N` | 각 일치 항목 앞뒤의 문맥 N줄 표시 |
| `-m N` | 파일별 N개 일치 후 중지 |
| `-j N` | 병렬 작업자 N개 사용 |
| `-p PATTERN` | AST 검색 패턴 |
| `-r TEMPLATE` | AST 재작성 템플릿(`-p` 필요) |
| `--glob GLOB` | 경로가 GLOB과 일치하는 파일만 포함 |
| `--type NAME` | 파일 유형 별칭 포함(`php`, `js`, `md` 등) |
| `--type-not NAME` | 파일 유형 별칭 제외 |
| `--lang NAME` | AST 언어. 기본값: `php` |
| `--json` | JSON 출력 생성 |
| `--no-ignore` | `.gitignore` 및 `.grephignore` 규칙 무시 |
| `--hidden` | 숨김 파일 포함 |
| `--dry-run` | 파일을 쓰지 않고 재작성 결과 출력 |
| `--interactive` | 재작성되는 각 파일 확인 |
| `--help` | 간단한 사용법 표시 |

---

## `greph-index`

워밍된 텍스트 인덱스, AST 팩트 인덱스 및 캐시된 AST 검색입니다.

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

### 텍스트 인덱스

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

텍스트 인덱스는 워밍된 트라이그램 및 식별자 게시 목록 저장소입니다. 기본적으로 인덱싱된 루트의 `.greph-index/`에 저장됩니다.

### 인덱스 세트

인덱스 세트를 사용하면 반복되는 다중 인덱스 워크플로우를 이름이 지정된 매니페스트로 관리할 수 있습니다.

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

기본 매니페스트 파일은 `.greph-index-set.json`입니다. 각 항목은 루트, 모드 및 수명 주기 프로필을 가리킵니다. `set build`과 `set refresh`는 활성화된 항목에서 작동하고, `set search`은 선택된 항목 전체에 검색을 분산하며 중복되는 일치 항목을 제거합니다.

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

AST 팩트 인덱스는 노드 수준의 팩트(호출, 인스턴스화, 클래스, 메서드)를 추출해 쿼리 가능한 저장소에 넣습니다. 조회는 팩트 키를 O(log n)한 다음 소스와 대조해 확인합니다. 기본적으로 `.greph-ast-index/`에 저장됩니다.

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

AST 캐시는 파싱된 트리를 디스크에 저장하므로 검색 시 파서를 완전히 건너뜁니다. 기본적으로 `.greph-ast-cache/`에 저장됩니다.

### 옵션

텍스트 검색 옵션은 `greph` 플래그 세트(`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`)과 일치합니다.

추가 플래그:

| 플래그 | 의미 |
|---|---|
| `--index-dir DIR` | 기본값이 아닌 워밍된 인덱스 디렉터리 사용. 다중 인덱스 검색 및 통계에서 반복 지정할 수 있습니다. |
| `--lifecycle PROFILE` | 빌드 정책: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | 기회적 새로 고침의 파일 임계값 |
| `--auto-refresh-max-bytes N` | 기회적 새로 고침의 바이트 임계값 |
| `--manifest FILE` | 인덱스 세트 매니페스트 로드. 기본값: `.greph-index-set.json` |
| `--mode MODE` | 세트 작업을 `text`, `ast-index` 또는 `ast-cache`으로 제한 |
| `--index NAME` | 세트 작업을 이름이 지정된 매니페스트 항목으로 제한. 반복 지정할 수 있습니다. |
| `--show-index-origin` | 워밍된 다중 인덱스 또는 세트 출력 앞에 일치하는 인덱스 항목 이름 추가 |
| `--trace-plan` | 워밍된 플래너 진단을 `stderr`으로 출력 |
| `--dry-refresh` | `stats`에서 워밍된 검색이 수행할 작업을 변경 없이 보고 |
| `--lang NAME` | `ast-index` / `ast-cache` 검색의 AST 언어. 기본값: `php` |
| `-j N`, `--jobs N` | AST 스캔용 작업자 |
| `-l`, `--files-with-matches` | 일치하는 파일 경로만 나열(AST 모드) |
| `--strict-parse` | 파싱 오류를 건너뛰지 않고 실패 처리 |
| `--fallback MODE` | 인덱스 누락 시 동작: `fail`(기본값) 또는 `scan` |
| `--help` | 간단한 사용법 표시 |

---

## `rg`

ripgrep 스타일 호환 래퍼입니다. 가장 흔히 사용하는 ripgrep 플래그를 지원합니다. 검증된 기능 범위는 [기능 매트릭스](https://greph.inline0.dev/ko/docs/advanced/feature-matrix)에 게시되어 있습니다.

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

### 예시

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

### 지원 옵션

| 플래그 | 의미 |
|---|---|
| `-F`, `--fixed-strings` | 고정 문자열 검색 |
| `-i`, `--ignore-case` | 대소문자를 구분하지 않는 검색 |
| `-w`, `--word-regexp` | 전체 단어 검색 |
| `-v`, `--invert-match` | 일치 결과 반전 |
| `-c`, `--count` | 일치하는 줄 수 계산 |
| `-l`, `--files-with-matches` | 일치하는 파일 나열 |
| `--files-without-match` | 일치하지 않는 파일 나열 |
| `-I`, `--no-filename` | 파일 이름 접두사 생략 |
| `-H`, `--with-filename` | 파일 이름 접두사 항상 출력 |
| `-n`, `--line-number` | 줄 번호 표시 |
| `-A N`, `--after-context N` | 각 일치 항목 뒤의 N줄 표시 |
| `-B N`, `--before-context N` | 각 일치 항목 앞의 N줄 표시 |
| `-C N`, `--context N` | 각 일치 항목 앞뒤의 N줄 표시 |
| `-m N`, `--max-count N` | 파일별 N개 일치 후 중지 |
| `-j N`, `--threads N` | 병렬 작업자 N개 사용 |
| `-e P`, `--regexp P` | 검색 패턴 |
| `-L`, `--follow` | 심볼릭 링크 따라가기 |
| `--glob GLOB` | 경로가 GLOB과 일치하는 파일만 포함 |
| `--type NAME` | 파일 유형 포함 |
| `--type-not NAME` | 파일 유형 제외 |
| `--json` | ripgrep 스타일 JSON 이벤트 출력 |
| `--no-ignore` | `.gitignore` 및 `.grephignore` 규칙 무시 |
| `--hidden` | 숨김 파일 포함 |
| `--files` | 검색하지 않고 후보 파일 나열 |
| `--help` | 간단한 사용법 표시 |

---

## `sg`

ast-grep 스타일 호환 래퍼입니다. 가장 흔히 사용하는 ast-grep 플래그를 지원합니다. 검증된 기능 범위는 [기능 매트릭스](https://greph.inline0.dev/ko/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`은 정식 ast-grep 동사입니다. `scan`와 `rewrite`은 일반적인 사용법을 반영하는 래퍼 전용 별칭입니다. 인수 없이 실행해도 일회성 검색을 수행합니다(`sg --pattern ... .`).

### 예시

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

### 지원 옵션

| 플래그 | 의미 |
|---|---|
| `-p`, `--pattern PATTERN` | AST 패턴 |
| `-r`, `--rewrite TEMPLATE` | 재작성 템플릿 |
| `-l`, `--lang NAME` | AST 언어. 기본값: `php` |
| `-j`, `--threads N` | 병렬 작업자 N개 사용 |
| `-i`, `--interactive` | 재작성할 때마다 확인 |
| `-U`, `--update-all` | 확인 없이 재작성 적용 |
| `--files-with-matches` | 일치 항목이 있는 파일 경로만 출력 |
| `--json[=STYLE]` | JSON 출력 생성. STYLE = `pretty`, `stream` 또는 `compact` |
| `--no-ignore [MODE]` | 저장소의 제외 규칙 무시 |
| `--hidden` | 숨김 파일 포함 |
| `--glob GLOB`, `--globs GLOB` | 경로가 GLOB과 일치하는 파일만 포함 |
| `--type NAME` | 파일 유형 포함 |
| `--type-not NAME` | 파일 유형 제외 |
| `--dry-run` | 파일을 쓰지 않고 재작성 미리보기 |
| `--help` | 간단한 사용법 표시 |

---

## 종료 코드

Greph은 grep / ripgrep 규칙을 따릅니다.

| 코드 | 의미 |
|---|---|
| `0` | 하나 이상의 일치 항목을 찾음(재작성의 경우 하나 이상의 파일이 변경됨) |
| `1` | 일치하는 항목을 찾지 못함 |
| `2` | 사용 오류 또는 런타임 실패(잘못된 인수, 인덱스 누락, `--strict-parse` 모드의 파싱 오류) |