명령어
query
특정 snapshot 범위에서 인덱싱된 지식을 검색합니다
무엇을 하는 명령인가
query는 인덱싱된 저장소 지식을 검색하고 질문에 맞는 hit를 반환합니다. 질문을 embedding하기 전에 정확히 요청한 커밋의 validated manifest와 canonical store를 요구하므로 다른 snapshot 결과를 조용히 대신 반환하지 않습니다.
언제 쓰는가 / 언제 쓰지 않는가
언제 쓰는가
- 질문에 대한 직접 검색 결과가 필요할 때
- 특정 커밋 시점에서 snapshot이 무엇을 알고 있는지 확인하고 싶을 때
- 더 큰 컨텍스트 패킷을 만들기 전에 가볍게 검색하고 싶을 때
언제 쓰지 않는가
- 토큰 예산이 있는 프롬프트 패킷이 필요할 때.
context pack을 사용하십시오. - working memory까지 포함해 현재 작업을 이어받고 싶을 때.
memory recall을 사용하십시오.
기본 구문
pnpm ragit query [question] [--input <path|->] [--top-k <n>] \ [--scope durable|session|harness|evidence|all] \ [--at <sha>] [--view minimal|default|full] [--explain] \ [--format text|json|both]
인자와 옵션
question: 직접 검색할 질문입니다.--input <path|->:question,topK, 선택적at, 선택적scope, 선택적 booleanexplain을 담은 JSON payload를 전달합니다.--top-k <n>: 반환 hit 개수를 조절합니다.--scope durable|session|harness|evidence|all: durable snapshot만 볼지, explicit artifact scope를 볼지, 둘을 합칠지 고릅니다.--at <sha>:HEAD, full commit SHA, unique hexadecimal commit prefix 중 하나를 사용합니다. Branch name, tag, revision expression은 허용하지 않습니다.--view minimal|default|full: hit 투영의 상세 수준을 선택합니다.--explain: 점수 입력과 기여도를 출력합니다.--view와 독립적이며 검색, deduplication, ranking을 바꾸지 않습니다.--format text|json|both: 출력 형식을 선택합니다.--cwd <path>: 다른 저장소를 대상으로 실행합니다.
입력/출력 계약
- 빠른 수동 호출에는 positional 입력이 적합합니다.
- 에이전트 자동화에서는
--input <path|->로 payload를 명시하는 편이 재현성이 좋습니다.
{
"question": "restore auth context",
"topK": 5,
"at": "HEAD",
"explain": true
}- JSON 출력은
query,snapshotSha,snapshot,explain,hits,warnings,redactionSummary를 반환합니다. snapshot은requestedRef,resolvedSha,selection,status,branch,detached,worktreeDirty를 보고합니다. 성공 시snapshotSha는 항상snapshot.resolvedSha와 같습니다.- 모든 view의 hit에는
citation: { id, sourceType, sourceId, sourceVersion, sourceSha }가 포함됩니다. 이는 source version을 식별하며 query text, rank, score, time, source text, absolute path는 포함하지 않습니다. scoreBreakdown은explain이 true일 때만 포함됩니다. hybrid 또는 keyword mode, vector/keyword 입력, authority/recency 기여도, final score를 보고합니다.- hit에는 필요할 경우
scope,originType,artifactId,artifactKind,authority,confidence같은 artifact-aware metadata가 함께 들어올 수 있습니다. - text/JSON 출력은 항상 다시 마스킹된 결과를 사용합니다.
--view minimal은 가장 작은 hit 형태를 반환합니다.--view default는 사람이 읽기 좋은 기본 투영입니다.--view full은 richer text를 유지하므로 context window 비용이 가장 큽니다.
점수와 Citation
- Hybrid retrieval subtotal:
alpha * vector + (1-alpha) * keyword, 기본alpha=0.7입니다. - 실제 candidate embedding을 계산하지 못한 artifact/evidence는 keyword mode
1.0 * keyword를 사용합니다. - Final score:
0.80 * retrieval + 0.15 * authority + 0.05 * recency입니다. - Exact score tie는 repository path, section, citation, chunk 순서로 결정적으로 정렬합니다.
--explain은 이미 계산된 breakdown을 투영할 뿐 candidate selection, scoring, deduplication, sorting, snapshot selection, source identity를 바꾸지 않습니다.
대표 사용 예시
사람용 터미널 예시:
pnpm ragit query "restore auth context" --format both
설명 포함 JSON 예시:
pnpm ragit query "restore auth context" --explain --view minimal --format json
에이전트 호출 예시:
pnpm ragit query --input query.json --view minimal --format json
실패/주의 사항
--input과 positionalquestion,--top-k,--scope,--at,--explain을 함께 쓰면 안 됩니다. 대신 JSON payload에explain: true를 넣으십시오. 출력 전용--view,--format,--cwd는--input과 함께 사용할 수 있습니다.question이 비어 있으면 실패합니다.--at이 없으면 정확한 현재 HEAD manifest만 읽습니다.--at HEAD를 포함해--at을 명시한 모든 호출은 explicit exact selection으로 보고됩니다.- Error details의 nearest indexed ancestor는 recovery hint일 뿐 자동 조회 결과가 아닙니다.
- Dirty worktree 조회는 커밋된 snapshot을 사용하고 uncommitted change를 제외하며 warning을 포함합니다.
- Invalid ref는 exit
2, exact snapshot 누락 또는 store unavailable은 exit3, corrupt 또는 unsupported manifest는 exit4를 사용합니다. Typed failure는 stable CLI failure envelope를 반환합니다. query는 working memory를 읽지 않습니다.--scope durable에서는 snapshot에 인덱싱된 콘텐츠만 검색합니다.--scope session|harness|evidence|all에서는 exact snapshot selection이 성공한 뒤에만 explicit artifact/evidence overlay를 함께 사용할 수 있으며, 결과는 여전히 sanitize된 상태로만 반환합니다.