jev-cli 사용하기
jev-cli는 "System One" 평가 모델인 Jev에게 하나의 공유된 state를 일련의 유형화된 questions에 대해 판단하도록 요청합니다. 선택, 점수 또는 확률과 같은 구조화된 JSON을 반환하며, 일반 텍스트는 절대 반환하지 않습니다.
코드가 분기할 수 있는 결정이 필요할 때 사용하세요. 전체 LLM 호출보다 훨씬 빠르고 저렴합니다(입력 토큰당 과금되며 출력 토큰은 0입니다). 따라서 diff, 로그 또는 지원 기록의 10가지 속성을 확인하는 것이 저렴합니다.
무언가를 작성, 요약, 번역 또는 재작성하는 데 사용하지 마세요. 텍스트를 생성할 수 없습니다.
평가만 실행하세요. 먼저 수행해야 할 설정 확인은 없습니다. eval은 문제가 있을 때 실행 가능한 메시지와 함께 빠르게 실패하고 고유한 종료 코드를 반환하며, jev-cli doctor는 그때 사용하는 진단 도구입니다. 모든 호출 전에 사용하는 것이 아닙니다.
평가 실행
jev-cli eval --state <text> --questions <json>
jev-cli eval -s "The support agent issued a full refund of \$40 and apologized." -q '{
"refunded": {"type": "boolean", "instructions": "Was a refund issued?"},
"tone": {"type": "choice", "instructions": "What tone did the agent use?",
"criteria": {"warm": "friendly and personal", "curt": "terse or dismissive"}},
"quality": {"type": "score", "instructions": "Rate how well this was handled.",
"criteria": ["poor", "acceptable", "excellent"]}
}'
{
"refunded": { "type": "boolean", "probability": 0.99 },
"tone": { "type": "choice", "choice": "warm", "probabilities": { "curt": 0.02, "warm": 0.98 } },
"quality": { "type": "score", "score": 1.78, "probabilities": { "0": 0, "1": 0.22, "2": 0.78 } }
}
인라인 형식은 직접 작성하는 짧은 문장에 적합합니다. 이미 파일에 있거나 명령 출력에 있는 내용의 경우 다음 입력 전달을 읽으세요. 대부분의 호출자가 실수하는 부분입니다.
입력 전달: 콘텐츠를 명령줄에 포함하지 마세요
기본적으로 --state-file / --questions-file을 사용하거나 -로 파이프하세요. 인라인 -s / -q는 실제로 직접 작성하는 짧은 텍스트용이며, 이미 어딘가에 존재하는 콘텐츠용이 아닙니다.
이는 에이전트가 호출자일 때 더 중요합니다.
- 인라인 콘텐츠는 토큰 단위로 생성되어야 합니다. 50KB diff를
-s에 붙여넣으면 ~15,000개의 출력 토큰을 방출하는 것을 의미합니다. 출력 요율로 청구되며, 생성이 직렬이므로 느리고, 이미 가지고 있는 콘텐츠를 다시 전송하므로 자동 잘림 및 드리프트가 발생할 수 있습니다. 경로는 ~10토큰이 소요되며, 파이프는 콘텐츠를 컨텍스트 창 밖에 완전히 유지합니다. - 셸은 인라인 콘텐츠를 재작성하며, 때로는 실행합니다. 큰따옴표 안에서
`cmd`는 명령 대체이고${VAR}는 확장됩니다.-s "const m = \echo hi`; const p = ${HOME}"를 전달하면 모델에const m = hi; const p = /Users/you`가 전송됩니다. 백틱이 실행된 것입니다. 신뢰할 수 없는 입력(PR diff, 사용자 로그)의 경우 이는 콘텐츠 손상뿐만 아니라 명령 실행 표면입니다. 작은따옴표에서는 콘텐츠의 아포스트로피 하나가 명령을 완전히 깨뜨립니다.
크기가 결정적인 요소는 아닙니다. ~150KB는 셸을 통해 잘 전달되며 Jev의 자체 예산이 먼저 제한됩니다. 콘텐츠 안전성과 토큰 비용이 이유입니다.
# 최적 — 콘텐츠가 모델 컨텍스트에 들어가지 않음
git diff | jev-cli eval --state-file - --questions-file ./checks.json
# 좋음 — 명령으로 준비하고 경로 전달
git log -20 --oneline > /tmp/state.txt
jev-cli eval --state-file /tmp/state.txt --questions-file ./checks.json
# 괜찮음 — 실제로 작성하는 짧은 텍스트
jev-cli eval -s "The agent issued a full refund." -q '{"r":{"type":"boolean","instructions":"Refunded?"}}'
# 잘못됨 — 이미 가지고 있는 파일을 셸을 통해 다시 전송
jev-cli eval -s "$(cat huge-diff.txt)" -q ...
하나의 입력만 stdin을 읽을 수 있습니다. 둘 다 큰 경우 하나는 파이프로 전달하고 다른 하나는 경로로 전달하세요. 질문 파일을 다시 내보내지 않고 호출 간에 재사용하세요.
상태가 일반 텍스트 대신 JSON인 경우 --state-json을 추가하세요.
세 가지 질문 유형
모든 질문에는 instructions가 필요합니다. instructions와 모든 기준 설명은 문자열, JSON 객체 또는 JSON 배열일 수 있지만, 단순한 숫자나 부울은 절대 안 됩니다.
| 유형 | criteria | 답변 |
|---|---|---|
boolean | 선택 사항 {"true": ..., "false": ...}, 각 측 생략 가능 | {"type":"boolean","probability":0.98} |
choice | 필수. 옵션 이름 → 설명 객체(null 가능) | {"type":"choice","choice":"warm","probabilities":{...}} |
score | 필수. 최소 2개 수준의 배열, 낮은 순서 | {"type":"score","score":1.83,"probabilities":{...}} |
사람들이 자주 실수하는 세 가지:
boolean은 부울이 아닌 P(true)를 제공합니다.0.98은 모델이 true에 98%를 할당한다는 의미입니다. 신뢰도가 아니며 보정되지도 않았습니다. 자신의 임계값을 선택하세요.0.5는 "true 또는 false가 동일하게 가능"함을 의미하며, "중간"이 아닙니다.score는0에서criteria.length - 1사이의 분수 위치입니다. 확률 가중 평균이며 인덱스가 아닙니다. 점진적인 평가에는boolean대신 이것을 사용하세요.choice는 옵션 이름을 그대로 반환하므로 코드에서 전환할 값으로 옵션 이름을 지정하세요. 확률의 합은 1이므로 정확히 하나의 승자를 선택합니다. "이 중 여러 개가 적용될 수 있음"의 경우 대신 후보당 하나의boolean을 사용하세요.
하드 제한
- 상태와 질문은 약 32,000 토큰(~150,000 영어 문자)의 예산을 공유합니다. 초과 시
{"error_type":"max_tokens_exceeded"}오류와 HTTP 400으로 실패합니다. - 텍스트만 가능합니다. 상태는 문자열, JSON 객체 또는 텍스트 배열이어야 합니다. 이미지, 오디오 또는 비디오는 허용되지 않습니다.
따라서 코드베이스, 전체 로그 아카이브 또는 대규모 말뭉치를 Jev에게 넘길 수 없습니다. 컴팩트한 인덱스나 발췌문을 미리 빌드하여 평가하세요. 구조화 방법은 references/patterns.md를 참조하세요.
한 번의 호출로 모든 것을 질문하세요
질문은 병렬로 독립적으로 평가됩니다. 서로를 보지 않습니다. 일괄 처리는 거의 공짜입니다. TypeSafe는 13개의 질문을 하나의 요청에 담는 것이 13개의 개별 요청보다 11.5배 저렴하고 9.6배 빠르며 동일한 답변을 측정했습니다. 그들의 문서는 코딩 에이전트가 사람들보다 질문당 한 번 호출하는 습관에 빠지기 쉽다고 언급합니다. 그러지 마세요.
필요할 수 있는 모든 것을 단일 요청으로 질문하고 사용하지 않는 것은 버리세요. 첫 번째 답변 없이는 정말로 구축할 수 없는 경우에만 두 번째 요청을 연결하세요.
결과 읽기
기본 출력은 질문 ID로 키가 지정된 bare answers 객체이므로 jq로 바로 파이프할 수 있습니다:
jev-cli eval --state-file - -q "$CHECKS" | jq -e '.deploy_ok.probability > 0.9' >/dev/null && echo healthy
사용량, 경고 및 providerMetadata(TypeSafe가 choice 및 score 답변에 대해 confidence를 보고하는 곳, 확률과는 별개)를 보려면 --full을 추가하세요. 단일 행 JSON을 보려면 --compact를 추가하세요.
종료 코드 및 오류
eval은 오류를 JSON({"error":{"code","message"}})으로 stderr에 기록하여 stdout을 깨끗하게 유지합니다. 항상 종료 코드로 분기하세요:
| 코드 | 의미 | 조치 |
|---|---|---|
0 | 성공 | stdout 파싱 |
1 | 제공자 또는 네트워크 오류 | 한 번 재시도; 지속되면 보고 |
2 | 잘못된 사용법 또는 유효하지 않은 질문 | JSON 수정 — 메시지가 문제가 있는 질문 ID와 필드를 지정합니다 |
3 | 누락되었거나 거부된 자격 증명 | 사용자에게 메시지를 전달; 재시도하지 마세요. 아래 참조 |
코드 2 메시지(예: questions.quality.criteria must list at least two ordered levels, but got 1)는 수정해야 할 정확한 경로를 가리킵니다.
오류 진단
호출이 실제로 실패한 경우에만, 그리고 코드 1 및 3에만 해당:
jev-cli doctor --offline # config, provider, model, key source — 네트워크 호출 없음
jev-cli doctor # 위 내용 + 하나의 작은 실시간 평가
코드 3은 제공자의 자체 단어를 전달하며, 다른 수정이 필요한 경우를 구분합니다. 누락된 키, 취소된 키, 청구 설정이 없는 계정 또는 플랜이 연결할 수 없는 모델은 모두 다르게 읽힙니다. 키가 잘못되었다고 가정하지 말고 해당 메시지를 전달하고, 절대 키를 생성하지 마세요. 키가 실제로 누락된 경우 사용자가 제공합니다:
jev-cli config set providers.vercel.apiKey <ai-gateway-key>
키를 다시 출력하지 마세요. config list는 --show-secrets가 전달되지 않는 한 키를 마스킹합니다.
구성 참조
구성 파일은 ~/.jev-cli/config.yaml에 있으며(JEV_CLI_HOME으로 디렉터리 재정의 가능), 권한은 0600으로 설정됩니다.
jev-cli config path # 파일 위치
jev-cli config list # 모든 값, 키는 마스킹됨
jev-cli config get providers.vercel.model
jev-cli config set providers.vercel.model typesafe-ai/jev
jev-cli config unset providers.vercel.baseURL
우선순위는 CLI 플래그 > 환경 변수(JEV_CLI_API_KEY, 그 다음 AI_GATEWAY_API_KEY) > 구성 파일입니다. CI에서는 JEV_CLI_API_KEY를 설정하고 구성 파일을 완전히 건너뛰세요.
provider는 현재 vercel(Vercel AI Gateway)만 허용합니다. jev 값은 TypeSafe의 공식 API용으로 예약되어 있으며 구현될 때까지 거부됩니다.
더 알아보기
- references/question-design.md — 답변을 사용 가능하게 만드는 질문 작성 및 상태 구성 방법: 원자적 질문, 복합 판단 분할, 단일 레이블 대 다중 레이블, 세 가지 유형 중에서 선택.
- references/patterns.md — 더 큰 문제를 위한 아키텍처: 추론적 팬아웃, 2단계 숏리스트, 분류 체계 및 코드베이스에 대한 계층적 분류, 신뢰도 기반 라우팅.
공식 문서 인덱스(에이전트가 읽을 수 있음): https://docs.typesafe.ai/llms.txt