시작 · 첫 검색

설치와 첫 검색

네이티브 CLI로 활용형을 찾고 결과를 읽는 최소 절차입니다. Node.js를 사용한다면 아래 npm 경량 CLI를 선택할 수 있습니다. 파일 탐색과 출력 형식의 차이는 설치와 CLI 선택에 정리되어 있습니다.

네이티브 CLI 설치

macOS와 Linux에서는 Homebrew가 실행 파일과 같은 버전의 형태 리소스를 설치합니다. 다른 배포 방식과 소스 빌드는 설치 안내를 확인합니다.

brew install seokminhong/brew/kfind
kfind --check-data

첫 검색

걷다는 찾을 표제어이고 --pos verb는 동사 지정을 뜻합니다. 파일을 만들지 않고 표준 입력으로 확인할 수 있습니다.

printf '길을 걸었다.\n' | kfind --pos verb 걷다

결과에는 원문의 길을 걸었다.가 표시됩니다. 검색어와 표기가 달라도 활용형 걸었다를 찾은 것입니다. 검색 결과가 있으면 종료 코드 0, 없으면 1, 오류면 2입니다.

파일을 검색하려면 질의 뒤에 경로를 붙입니다. -n은 네이티브 CLI의 줄 번호 옵션입니다.

kfind -n 걷다 src docs

결과의 경로와 줄 번호로 원문을 열어 뜻을 확인합니다. 경로가 없으면 pipe 입력을 검색하며, 대화형 터미널에서는 현재 디렉터리를 검색합니다. 결과가 예상과 다르면 결과 없음 점검을 따릅니다.

npm 경량 CLI

Node.js 20 이상에서는 다음 명령으로 같은 표제어를 검색할 수 있습니다. npm CLI는 일치한 부분 문자열을 출력하며 네이티브의 줄 출력과 다릅니다.

printf '길을 걸었다.\n' | npx @kfind/kfind@1.1.0 --pos verb 걷다

애플리케이션에서 문자열을 검색하려면 JavaScript API를 사용합니다. 패키지에는 full POS 사전이 없으며, API에 필요한 추가 리소스는 호출자가 bytes로 전달합니다.

품사, 구와 대안 검색

명사에는 n:, 동사에는 v: 태그를 붙일 수 있습니다. 공백은 같은 줄에서 순서대로 나타나는 구를, |는 단일 atom 중 하나를 찾는 대안을 뜻합니다.

kfind 'n:사용자 v:검증하다' src
kfind 'v:걷다 | n:사용자 | n:검증' src
kfind --literal 걸었다 docs

--literal은 입력 표기 그대로 찾습니다. 질의 문법에서 인용·태그 규칙을, 구 검색에서 간격 제한을 확인할 수 있습니다.

자동화 출력

네이티브 CLI에서는 다음처럼 사전·품사·경계·출력을 명시합니다. any는 더 넓은 후보를 반환하므로 원문 문맥을 읽어 불필요한 결과를 제외합니다.

kfind --embedded --boundary any --pos verb --json 걷다 src

JSON Lines는 네이티브의 byte 좌표와 npm의 UTF-16 좌표를 구분합니다. 결과가 없다는 상태는 관련 내용이 전혀 없다는 보장이 아닙니다.

에이전트 통합

에이전트도 위 명령을 직접 실행할 수 있습니다. 세션 지침과 실행 전 hook을 자동 설치하려면 skill 설치를 확인합니다. 통합 hook은 고정 문자열 모드를 명시하지 않은 한글 패턴의 rg·grep·git grep 명령을 차단합니다. 정확한 표기 검색의 -F, --fixed-strings와 fgrep은 허용합니다.