Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI

프로젝트에서 artifactize verify --all --wait를 실행하면 리뷰가 시작됩니다. 명령은 Run ID를 알려 주고, Run이 끝나면 eval마다 결과를 출력하며, 모두 GREEN이면 0으로 종료합니다. 이 페이지는 모든 명령의 플래그, 출력, 종료 코드를 정리하고, 이어서 verify의 정책, 예산, 선택 파일, 프로필 변형을 자세히 설명합니다.

명령 레퍼런스

모든 명령에서 --repo PATH, --state-dir PATH, --json은 하위 명령 앞이나 뒤에 각각 한 번만 지정할 수 있습니다. 저장소를 읽는 명령은 --repo를 생략하면 대개 현재 디렉터리를 쓰지만, 기본값은 명령마다 다릅니다. doctor는 --repo를 직접 줄 때만 프로젝트 선언을 확인합니다. Monitor와 Review는 아래 설명처럼 ALL에서 시작합니다. 상태는 기본으로 공유 상태 디렉터리에 저장됩니다. 저장소나 상태를 쓰지 않는 명령은 이 옵션들을 무시합니다. Monitor와 Review는 --json을 거부합니다. mcp는 항상 stdout에 JSON-RPC를, stderr에 시작할 때의 진단 메시지를 씁니다. 현재 디렉터리 도구의 출력은 이미 아래 표처럼 텍스트나 JSON이므로 --json을 줘도 바뀌지 않습니다. tools help에서 프로그램 인자 뒤에 오는 플래그는 artifactize가 아니라 그 프로그램에 전달됩니다. SELECTOR 자리에는 위치 인자 ARTIFACT나 ARTIFACT/EVAL, --eval ID, --evals CSV, --artifacts CSV, --evals-file PATH, --artifacts-file PATH, --all 중 하나만 씁니다. CSV는 verify --evals app/lint,app/tests나 verify --artifacts app,docs처럼 이름이나 eval ID를 쉼표로 이은 목록입니다. --evals와 --artifacts는 여러 번 줄 수 있으며, 값은 순서대로 합쳐지고 중복은 빠집니다. help [COMMAND]와 -h/--help는 도움말을 출력합니다. 명령 없이 artifactize만 실행해도 도움말이 나옵니다(종료 코드 0, --json을 줘도 텍스트). -V/--version은 루트 명령과 artifactize tools에서 버전을 출력합니다.

명령플래그출력종료 코드
verify SELECTOR--profile NAME, --recursive, --force, --jobs N(필요할 때만), --fingerprint-jobs N(CPU 수), --max-executions N, --wait 또는 --watch, --request-key KEY, --comment TEXT, --reuse-only KINDS, --speculateRun ID 또는 {run,state}를 출력합니다. --wait면 최종 텍스트/JSON을, --watch면 JSON 줄 이벤트를 출력합니다접수되면 0, --wait나 --watch면 Run 결과
status [SELECTOR]--profile NAME, --recursive, --force, --fingerprint-jobs N(CPU 수). 기본값은 --all입니다텍스트 또는 JSON충족하면 0, 아니면 1
mcpMCP stdio 프로토콜입니다. 진단은 stderr로 출력합니다정상적으로 연결이 끊기면 0
config check텍스트 또는 JSON0
config graph [ARTIFACT]--impact텍스트 또는 JSON0
run list--repo-only | --all, --limit N(50), --offset N(0)텍스트 또는 JSON0
run watch RUN_IDJSON 줄로 상태 변화, eval 결과, 최종 검증Run 결과
run cancel RUN_ID취소 요청을 받았다는 JSON0
run show RUN_ID--wait, --timeout-ms MS(600000, --wait 필요)JSON0, --wait면 Run 결과
request list--run RUN_ID텍스트 또는 JSON0
request show IDJSON0
request logs ID--stream stdout|stderr|both, --tail N, --start N, --end N, --search TEXT크기가 제한된 증거 JSON0
request claim ID--reviewer NAME($USER)JSON0
request unclaim ID--reviewer NAME($USER)JSON0
request tool ID TOOL--reviewer NAME텍스트 또는 JSON0, 도구 오류면 2
request submit ID--verdict GREEN|RED, --fields JSON | --fields-file PATH, --reviewer NAMEJSON0, RED여도 0
session show REF--summary텍스트, 또는 저장된 이벤트(또는 요약)를 담은 JSON0
session send REF MESSAGE텍스트 또는 JSON0
cache list--history텍스트 또는 JSON0
cache show KEY--historyJSON0, 없으면 4
cache rm KEYJSON0
tools check [EVAL]--eval ID, --artifact ID, --audience agent|human, --tool NAME, --execute, --args JSONJSON준비됐으면 0, 아니면 1
tools read PATH—UTF-8 텍스트성공 0, 도구 오류 1, 사용법 오류 2
tools list [PATH]—JSON성공 0, 도구 오류 1, 사용법 오류 2
tools glob PATTERN [PATH]—JSON성공 0, 도구 오류 1, 사용법 오류 2
tools grep PATTERN [PATH]--glob GLOB, --case-insensitiveJSON성공 0, 도구 오류 1, 사용법 오류 2
tools section PATH HEADING—Markdown 텍스트성공 0, 도구 오류 1, 사용법 오류 2
tools help PROGRAM [SUBCOMMAND...]뒤따르는 인자는 --help 앞에 붙여 PROGRAM에 전달합니다텍스트성공 0, 도구 오류 1, 사용법 오류 2
tools open TARGET—기본 애플리케이션으로 엽니다성공 0, 도구 오류 1, 사용법 오류 2
login codex로그인 URL은 stderr에 출력합니다. 터미널에 붙여 넣은 리디렉션 URL을 표준 입력에서 읽을 수 있습니다Signed in with Codex.라고 출력합니다. JSON은 {"provider":"codex","signed_in":true}입니다0
login openai|anthropic|geminiAPI 키를 stdin에서 읽습니다Saved the PROVIDER API key.라고 출력합니다. JSON은 {"provider":…,"saved":true}입니다0
logout codex로컬 토큰을 지우고 폐기를 시도합니다. 읽기 전용 인증 파일은 건드리지 않습니다Signed out of Codex.라고 출력합니다. JSON은 {"provider":"codex","signed_in":false,"revoked":BOOL}입니다로컬 로그아웃 뒤 0
logout openai|anthropic|gemini저장한 키를 지웁니다. 변수는 건드리지 않습니다Forgot the saved PROVIDER API key.라고 출력합니다. JSON은 {"provider":…,"saved":false}입니다0
login claude-agentClaude Code 자체 명령인 claude auth login을 실행합니다. 그 URL은 stderr에 출력하고, stdin에 붙여 넣은 코드는 Claude Code에 전달합니다Claude Code is signed in with METHOD (PLAN).이라고 출력합니다. Claude Code가 요금제를 알려 주지 않으면 (PLAN) 부분을 뺍니다. 로그인한 뒤 확인한 상태에 로그인 정보가 없으면 Claude Code signed in.이라고 출력합니다. JSON은 {"provider":"claude-agent","signed_in":true}입니다0. claude가 없거나 Claude Code가 실패하면 2
logout claude-agentClaude Code 자체 명령인 claude auth logout을 실행합니다Signed out of Claude Code.라고 출력합니다. JSON은 {"provider":"claude-agent","signed_in":false}입니다0. claude가 없거나 Claude Code가 실패하면 2
provider list기본 provider별 키 출처와 커스텀 provider 전체를 보여 줍니다. 키 값은 출력하지 않습니다. 형식은 텍스트 또는 JSON입니다0
provider add NAME--alias PROVIDER, 또는 --api API --url URL과 선택 항목 --key(키는 stdin에서 읽습니다. 없으면 엔드포인트에 키가 없습니다)Saved custom provider NAME.라고 출력합니다. JSON은 {"provider":NAME,"saved":true}입니다0
provider remove NAMERemoved custom provider NAME.라고 출력합니다. JSON은 {"provider":NAME,"saved":false}입니다0
remote login URL--share summary|full(summary). 토큰은 stdin으로 받습니다Signed in to URL as NAME (scopes: …).라고 출력합니다. JSON은 {"url":…,"share":…,"principal":…,"scopes":[…]}입니다0
remote logoutSigned out of the remote review store.와 함께, 서버에서는 server token revoke 전까지 토큰이 유효하다고 안내합니다. JSON은 {"signedIn":false}입니다0
remote statusURL, 공유 수준, 토큰 출처, 접속 가능 여부를 보여 주고, 이어서 주체와 범위 또는 오류를 보여 줍니다. JSON은 아래를 참고하세요로그인 상태면 0, 아니면 1
remote push--dry-run텍스트 또는 JSON0
models PROVIDER기본 provider나 커스텀 provider텍스트 또는 JSON0
doctor텍스트 또는 JSON준비됐으면 0, 심각한 오류면 1
limits--signoff-idle-grace SECONDS(0–86400)지금 적용되는 머신 전체 한도를 보여 줍니다. 형식은 텍스트 또는 JSON입니다0
prune--older-than DURATION, --dry-run텍스트 또는 JSON0
monitor [PATH]ALL에서 시작합니다. PATH나 --repo PATH는 처음 고를 저장소만 정합니다. --all은 경로와 함께 쓸 수 없습니다터미널 UI0
review [REQUEST_ID]--repo PATH(repo: 검색어), --all(기본값이며 --repo와 함께 쓸 수 없습니다), --reviewer NAME($USER)터미널 UI0
server run--listen ADDR(127.0.0.1:8417): 숫자로 쓴 IP:PORT(IPv6은 [::1]:8417) 형식이며, 호스트 이름은 사용할 수 없습니다. 포트가 0이면 사용 가능한 포트를 골라 그 번호를 출력합니다Listening on http://ADDR/라고 출력합니다. JSON은 {"listen":ADDR}입니다0
server token add NAME --scopes SCOPES--scopes(필수이며 기본값은 없습니다. read, publish, human을 쉼표로 이은 목록입니다)토큰을 한 번 출력하고 저장해 두라고 안내합니다. JSON은 {"name":NAME,"scopes":[...],"token":TOKEN}입니다0
server token list텍스트 또는 JSON0
server token revoke NAME--purgeJSON(--json이 없어도)0
server rm KEYJSON0

verify --wait와 run show --wait는 Run 결과에 따라 종료 코드가 정해집니다. GREEN이면 0, RED이면 1, ERROR 또는 취소면 2, INCOMPLETE면 4, YELLOW면 5입니다. YELLOW는 승인이 남아 있을 뿐, 승인된 상태는 아니라는 뜻입니다. 옵션 없는 verify는 검증 결과와 관계없이 Run이 접수되면 종료 코드 0으로 끝납니다. Ctrl-C로 지켜보기를 중단하면 명령은 종료 코드 130으로 끝나지만 Run은 계속 실행됩니다. run show --wait는 RUNNING이나 WAITING_HUMAN 상태의 Run이 끝날 때까지 상태를 계속 확인합니다. Run이 끝나기 전에 이 명령의 제한 시간이 지나면 현재 Run을 출력하고 3으로 종료하며, Run은 계속 실행됩니다. 모든 명령은 사용법 오류(알 수 없는 옵션, 반복할 수 없는 옵션의 반복, 충돌하거나 빠진 옵션과 값)나 동작 오류가 나면 종료 코드 2로 끝납니다. 오류는 stderr에 텍스트로, 또는 --json이면 stdout에 {"error":"..."}로 나옵니다(stdout을 프로토콜에만 쓰는 mcp는 예외). 도구 실패에는 두 가지 예외가 있습니다. 현재 디렉터리 도구(tools read, list, glob, grep, section, help, open)는 --json을 줘도 공유 도구 실행기의 종료 코드 1과 진단 메시지를 그대로 씁니다. request tool로 실행한 Human 도구가 실패하면 평소와 같은 결과(출력된 내용, --json이면 {"content":[…],"isError":true})를 stdout에 출력하고 2로 종료합니다. tools check는 선언, 사전 점검, 실행, 정리 실패를 진단 보고서에 담고(--execute 호출이 실패한 경우 포함) 1로 종료합니다. 세 경우 모두 사용법 오류는 일반 규칙을 따릅니다. plan, history, --full은 없습니다.

목록 옵션인 --reuse-only와 server token add --scopes는 여러 번 줄 수 있으며, 쉼표로 구분한 값이 모두 합쳐집니다. 공통 옵션인 --repo, --state-dir, --json은 한 번만 받습니다. run show --timeout-ms는 1부터 2147483647까지의 정수(밀리초)여야 하며, 범위를 벗어나면 사용법 오류(종료 코드 2)입니다.

logout codex가 0을 돌려주는 것은 로컬에서 로그아웃했다는 뜻이지, 서버에서 토큰이 폐기됐다는 뜻은 아닙니다. 서버에 토큰 폐기를 요청하지만, 폐기가 성공한다고 보장하지는 않습니다. 폐기를 확인하지 못하면 stderr에 경고하고, JSON 결과에 "revoked":false가 들어갑니다(확인되면 true). 로컬 토큰은 그래도 지워지며, 읽기 전용 외부 인증 파일은 절대 바꾸지 않습니다.

식별자 인자

Run ID와 요청 ID 인자(request list --run과 review REQUEST_ID 포함)는 ASCII 글자, 숫자, -, _, .로 이뤄진 1–200자여야 하며 점만으로 이뤄질 수는 없습니다. cache show, cache rm, server rm의 재사용 키 인자는 정확히 64자의 소문자 16진수여야 합니다. 형식이 잘못된 식별자를 지정하면 사용법 오류로 처리하고 종료 코드 2로 끝납니다. 형식은 맞지만 해당 재사용 키로 저장된 기록이 없으면 cache show는 null(--history면 [])을 출력하고 4로 종료하며, cache rm은 removed: false를 알립니다.

server token add NAME과 server token revoke NAME은 글자, 숫자, -, _, .로 이뤄진 1–64자의 ASCII를 받습니다. 빈 이름, 공백, 슬래시, ASCII가 아닌 글자, 너무 긴 이름은 거부되며 2로 종료합니다. 이 이름은 표시용이며, 인증에 쓰는 비밀 토큰이 아닙니다.

session show와 session send는 Agent 리뷰의 저장된 대화를 읽고 이어 갑니다. 인자, 출력, 오류는 Agent 세션에 있습니다.

이전 버전의 상태를 여는 명령은 상태에서 설명한 대로 그 상태를 업그레이드합니다. 열 수 없는 상태면 2로 종료하고, doctor는 이를 심각한 오류로 알리고 1로 종료합니다.

제출과 지켜보기

옵션 없는 verify는 Run을 제출하고 Run ID를 출력한 뒤, 접수되면 0으로 종료합니다. 스크립트에서 결과에 따른 종료 코드가 필요하면 --wait를 붙이세요. 같은 --request-key로 다시 제출하면 처음 만든 Run을 돌려줍니다. 키는 ASCII 글자, 숫자, ., _, :, -로 이뤄진 1–128자이며, 조건에 맞지 않는 키를 쓰면 명령이 종료 코드 2로 끝납니다. 자세한 내용은 제출, 지켜보기, 취소에 있습니다.

--comment TEXT를 붙이면 지금 하는 일을 짧게 적어 Run과 함께 남기고, Run을 지켜보는 사람이 이를 볼 수 있습니다. Run의 동작은 바뀌지 않습니다. 코멘트는 제어 문자와 앞뒤 공백이 없는 한 줄이어야 하며, 길이는 1–200자여야 합니다. 조건에 맞지 않으면 종료 코드 2로 끝납니다. verify --wait는 Comment: 줄에, run list는 COMMENT 열(없으면 -)에 보여 주고, verify --wait, run list, run show의 JSON에는 comment로 나옵니다. --wait 없이 verify가 출력하는 JSON은 Run과 그 상태만 알려 줍니다.

artifactize verify --all --request-key build-42
artifactize verify --all --comment "Fixing the login form"
artifactize run show RUN_ID --wait
artifactize run cancel RUN_ID

verify --wait는 Run ID를 stderr에 출력한 뒤 Run이 끝나면 eval별 결과를 보여 주고, Run의 종료 코드를 반환합니다. Run 자체의 진단(최대 64 KiB)과 Run 오류도 stderr에 나오며, --json일 때도 마찬가지입니다. runtime-relations 예제에서 GREEN, RED, 막힌 eval을 나란히 볼 수 있습니다.

Verify 모드

--speculate는 요청마다 켜는 스위치이며, 기본으로 꺼져 있습니다. 접수된 Run은 modes: {speculate}를 기록하며, 같은 --request-key로 다시 시도하면 처음 요청의 선택을 그대로 씁니다.

모드실행 방식
기본실행 게이트가 막지 않으면 eval을 시작합니다. 선택한 승인이 아직 대기 중이어도 그에 의존하는 eval은 바로 실행되며, GREEN 결과는 승인 결과가 GREEN이 될 때까지 PROVISIONAL로 표시됩니다
--speculate게이트가 정해지기 전에 Runtime과 Agent 리뷰를 시작합니다

승인은 앞선 eval이 통과하기 전에 추측으로 미리 요청하지 않으며, --speculate Run에서도 앞선 eval이 통과하면 평소처럼 요청합니다. 승인을 언제 요청하는지, 그 승인에 의존하는 eval이 어떻게 실행되는지는 승인과 Run 종료를 보세요. --speculate에서는 새로 준비된 작업을 실행할 --jobs나 백엔드 자리가 모자라면 artifactize가 실행 중인 추측 실행 리뷰를 중단할 수 있습니다. 그 리뷰는 나중에 다시 시작하며, 다시 시작할 때도 --max-executions로 정한 실행 횟수에 한 번 더 포함됩니다. 추측 실행은 실행 순서를 바꿀 뿐 승인 여부를 바꾸지 않습니다. verify --wait는 평소와 같은 Run 결과 종료 코드로 끝납니다. 추측 실행의 스케줄링과 취소는 추측 실행에서 설명합니다.

Runtime CLI

선택자, 게이트, 결과, 출력은 Run, 상태, 검증에서 다룹니다.

없어진 예전 게이트 우회 설정은 업그레이드 안내를 보세요. --force는 직접 선택한 실행 가능한 eval만 새로 리뷰하도록 표시하며, 재귀로 포함된 의존성에는 적용되지 않습니다. 실행 범위를 넓히거나 게이트를 건너뛰지도 않습니다. Run에는 결정된 정책과 각 요청의 force 여부가 기록됩니다. 강제로 실행하는 eval은 캐시 결과를 읽지 않고, 실행 중인 작업에도 합류하지 않습니다. --force로 새로 실행한 eval의 결과가 GREEN이나 RED면 그 키의 가장 최근 기록으로 추가되고, 리뷰 저장소가 설정되어 있으면 게시되어 이후 Run이 재사용합니다. 의존성은 로컬 기록을 계속 재사용할 수 있지만, --force로 실행한 Run은 저장소에서 아무것도 읽지 않습니다. 추측 실행과 대기 중인 승인도 최종 검증 요건을 면제하지 않습니다.

동시에 실행되는 Run이 언제 같은 리뷰에 합류하는지, --force가 이를 어떻게 바꾸는지는 Run끼리 작업 나누기에서 설명합니다.

eval 동시 실행 수에는 기본 상한이 없어서, READY인 eval은 준비되는 즉시 시작합니다. 동시 실행이 문제를 일으킬 때만 --jobs N(1–4294967295)을 붙이세요. 그러면 이 Run의 eval 수가 제한됩니다. Agent 리뷰는 이와 별개로 $STATE/limits.json에 따라 머신 전체에서 백엔드마다 제한됩니다(백엔드 수용량). 백엔드 자리가 빌 때까지 대기 중인 요청은 --jobs의 동시 실행 수에도, 실행 시작 횟수에도 포함되지 않습니다.

--fingerprint-jobs N(verify와 status, 1–4294967295)은 fingerprint를 동시에 몇 개까지 계산할지 정합니다. 기본값은 프로세스가 쓸 수 있는 CPU 수입니다. verify에서는 준비 단계와 Runtime/Agent 리뷰가 끝날 때 하는 재확인이 한도 하나를 함께 쓰며, eval 수를 제한하는 --jobs와는 별개입니다. Human 도구 실행과 제출은 CPU 수만큼 따로 fingerprint를 계산하며 이 설정을 따르지 않습니다. 결과와 출력은 이 한도나 완료 순서와 상관없이 같습니다.

verify --max-executions N은 Run 하나에서 실행을 시작할 수 있는 횟수를 0–18446744073709551615 사이로 정합니다(생략하면 무제한). Artifact 선언 필드가 아닙니다. Run은 직접 지정한 jobs 상한(무제한이면 필드가 없음), fingerprintJobs, maxExecutions, executionsStarted를 기록합니다. Runtime이나 Agent 리뷰는 실행 준비가 끝나면 시작 횟수를 1 늘리며, 이후 프로그램을 시작하지 못하거나 리뷰가 ERROR로 끝나도 이 횟수는 유지합니다. 사람의 판정을 기다리는 시간, 담당 지정, Human 도구 사용은 시작 횟수에 포함되지 않습니다. fingerprint 계산과 재확인, 저장된 결과 재사용, 이미 실행 중인 리뷰에 합류하는 것도 마찬가지입니다. 실행할 준비가 끝나기 전에 실패한 리뷰도 시작 횟수에 넣지 않습니다. execution_paths에 지정한 도구 파일을 읽지 못한 Agent 리뷰는 시작 횟수에 들어가고, 모델을 호출하지 않은 채 ERROR/PREPARATION_FAILED로 끝납니다. 0으로 두면 재사용, 합류, Human 리뷰만 할 수 있습니다. 합류한 Run이 실패해서 리뷰를 다시 실행해야 하면, 다시 실행하는 리뷰는 그 리뷰가 속한 Run의 남은 횟수를 씁니다. 횟수를 다 써도 실행 중인 eval은 멈추지 않지만, 남은 READY 요청은 BUDGET_EXHAUSTED가 되고 Run은 이유와 함께 INCOMPLETE(종료 코드 4)로 끝납니다. 모든 요청을 시작했다면 실행 횟수가 한도에 정확히 도달해도 오류가 아닙니다.

Human 대기와 취소는 제출, 지켜보기, 취소를 따릅니다. 담당 지정, 도구, 승인은 Human 가이드에서 다룹니다.

선택 파일은 4 MiB 이하의 일반 파일이어야 합니다. ID를 JSON 문자열 배열로 담거나, 앞뒤 공백을 뺀 ID를 한 줄에 하나씩 담으세요. UTF-8 BOM과 CRLF도 쓸 수 있습니다. 중복을 빼기 전 기준으로 ID가 1–100000개여야 합니다. 빈 줄은 무시하며, ID에는 ASCII 공백, 제어 문자, 쉼표를 쓸 수 없습니다. 형식이 잘못된 JSON 배열을 줄 단위 형식으로 다시 읽지는 않습니다. 상대 경로는 --repo가 아니라 CLI의 현재 디렉터리를 기준으로 합니다.

verify ... --profile NAME은 선택과 재귀 정책으로 정한 범위에 포함된 실행 가능한 모든 eval에서 이름이 NAME인 profile_variants 항목을 통째로 선택합니다. 변형은 그다음에 적용됩니다. 실행 가능한 eval마다 이름 규칙에 맞는 프로필 변형을 최대 64개 선언할 수 있으며, 각 변형은 원래 리뷰어 종류를 유지합니다. 없는 변형 이름을 주면 Run을 만들기 전에 실패하며, 원본 선언 파일은 수정하지 않습니다. --recursive를 주면 이미 선택된 의존성에도 변형이 적용됩니다. 예를 들어 app/review --profile fast가 실행하는 Runtime 변형의 인자에 {fixtures}가 있으면, fixtures의 eval은 fast가 아니라 기본 프로필로 Run에 들어옵니다. 고른 변형은 실행 옵션일 뿐 재사용 키에 들어가지 않습니다. 따라서 Runtime 변형에서 명령이나 인자를 바꾸지 않았다면, 프로필 변형이나 기본 프로필이 달라도 결과를 서로 재사용할 수 있습니다. 저장된 요청의 profile과 options는 결과를 만든 실행을 나타내고, 캐시가 다른 프로필의 결과를 돌려주면 requestedProfile에 요청한 프로필이 남습니다. 텍스트 출력은 결과를 만든 프로필의 설정이 다를 때만 재사용 표시에 profile NAME을 붙입니다. 설정이 같은 변형의 결과에는 표시가 붙지 않으며, 저장된 options.variant로 구분합니다.

재사용만 하기

verify --reuse-only KINDS는 runtime, agent, human을 쉼표로 이은 목록을 받습니다. 목록에 있는 종류의 eval은 기존 결과만 재사용할 수 있습니다. 재사용할 수 있는 것은 로컬 캐시에 있는 그 재사용 키의 완료된 기록이나, 설정되어 있다면 리뷰 저장소에 있는 기록입니다. 그런 기록이 없으면 eval을 실행하지 않습니다. 실행 프로세스를 시작하거나 provider를 호출하거나 Human 요청을 만들지 않으며, 같은 재사용 키의 리뷰가 진행 중이어도 거기에 합류하지 않습니다. 강제로 실행하는 eval은 캐시 결과를 읽지 않으므로, 목록에 있는 종류에 --force를 주면 절대 실행되지 않습니다. 목록에 없는 종류는 평소처럼 실행합니다. CI에서 artifactize verify --all --wait --reuse-only agent,human을 쓰면 테스트는 실행하고 리뷰는 모두 캐시나 저장소에서 가져옵니다(CI).

실행하지 않은 eval은 STALE로 표시되고, 이유는 blockedReason에 나옵니다.

  docs/review [run-Hq2b9X-4]: STALE — Not reused (--reuse-only agent): no cached or stored result, so it was not executed.

이 eval에 의존하는 eval도 다른 증거가 없을 때와 마찬가지로 대기 상태가 되거나 실행이 차단됩니다. 예산을 다 썼을 때처럼, 다른 eval이 RED나 ERROR여도 Run은 이유와 함께 INCOMPLETE(종료 코드 4)로 끝나며, 그 종류들을 reuseOnly로 기록합니다. status는 이 플래그를 받지 않으며, 옵션 없는 verify가 무엇을 할지 예측합니다.

의존성 선택과 출력

artifactize verify app/e2e는 --eval app/e2e처럼 그 eval을 선택합니다. 필요한 의존성 범위의 eval까지 실행하려면 --recursive를 붙이세요. 붙이지 않으면 입력 증거가 이미 있어야 합니다. Artifact를 선택하면 그 부분의 eval과, 같은 순환에 속해 그 Artifact를 리뷰하는 다른 Artifact의 eval도 함께 실행됩니다. --force는 선택한 Artifact와 그 부분의 eval만 새로 리뷰하도록 표시하며, 순환에 속한 다른 Artifact나 의존성에는 적용되지 않습니다. 파일 Artifact는 선언된 이름으로 선택하며, 파일 Artifact를 둘러싼 폴더 Artifact를 선택하면 부분인 파일 Artifact도 함께 선택됩니다.

의존성 순환을 포함해 어떤 eval이 대기 상태가 되거나 실행이 차단되는지는 eval 의존성을 보세요.

status 출력의 동작 값은 execute, reuse, wait, blocked입니다. 요청, 검증, status에는 blockedBy로 eval ID가 들어갑니다. 태그, 파일 종류, 경로는 graph와 status 출력에 나오고, Monitor는 이를 화면에 보여 줍니다.

status 상태

status는 Artifact와 eval마다 상태를 출력합니다. 상태는 저장된 판정이 아니라 지금의 파일과 선언을 기준으로 합니다. 저장된 GREEN 결과의 재사용 키가 현재 키와 일치하면 PASS로 표시되며, 동작 항목에는 다음에 verify를 실행하면 무엇을 할지 나옵니다.

상태evalArtifact
PASS현재 재사용 키에 맞는 GREEN 결과가 있고 게이트도 충족합니다eval이 모두 PASS이고, 부분과 의존하는 Artifact도 모두 검증 요건을 충족합니다
RED현재 재사용 키에 맞는 RED 결과가 있습니다eval이나 부분 중 하나가 RED입니다
BLOCKED게이트가 RED입니다eval이나 부분 중 하나가 BLOCKED입니다
WAIT_DEPENDENCY게이트에 아직 현재 결과가 없습니다eval이나 부분 중 하나가 대기 중입니다
WAITING_HUMAN이전 버전의 artifactize가 요청했고 아직 사람이 처리하지 않은 승인이 있습니다—
DEFERRED다른 작업을 막지 않으며, 아직 사람이 처리하지 않은 승인 요청이 있습니다eval이나 부분 중 하나가 DEFERRED입니다
PROVISIONALGREEN이지만 게이트가 아직 DEFERRED나 PROVISIONAL입니다eval이나 부분 중 하나가 PROVISIONAL입니다
STALE전에 리뷰했지만 현재 재사용 키에 맞는 결과가 없습니다(이전 오류, 키 없는 결과, --force 포함)eval이나 부분 중 하나가 STALE입니다
UNREVIEWED리뷰한 적이 없습니다리뷰한 eval이 없거나, eval도 부분도 없습니다
INCOMPLETE—그 Artifact의 eval은 PASS이지만 의존하는 Artifact의 검증 요건이 충족되지 않습니다
BASIS—의존하는 Artifact가 모두 검증 요건을 충족한 basis Artifact입니다

Artifact의 eval과 부분의 상태 중 RED, BLOCKED, WAIT_DEPENDENCY, DEFERRED, PROVISIONAL, STALE, UNREVIEWED에 해당하는 것이 여러 개라면, 이 목록에서 가장 앞에 있는 상태를 Artifact에 표시합니다. 그래서 자기 eval이 없는 Artifact는 부분의 상태를 그대로 보여 줍니다. ERROR는 Run 출력에만 나오며, status는 마지막 시도가 실패한 eval을 STALE로 보여 줍니다.

저장된 Run 증거와 터미널 화면

저장된 증거가 있으면 run show RUN_ID --json과 verify --wait --json의 출력 객체 최상위에 evidence 필드가 들어갑니다. Run 필드는 run으로 감싸지 않고 출력 객체에 바로 들어갑니다. evidence에는 이 Run에서 새 요청을 만들지 않고 사용한 저장된 판정이 eval ID별로 담깁니다. 일부 eval만 실행한 Run에서 상위 eval의 결과를 캐시에서 가져와 쓴 경우가 그 예입니다. 전체 기록에서 가장 최근 판정을 담는 것은 아닙니다. Run을 보세요. 터미널에서 쓰는 키와 화면 배치는 Monitor와 Human 리뷰에 있습니다.

현재 디렉터리 도구

artifactize tools read|list|glob|grep|section|help|open ...은 내장 도구를 현재 디렉터리에서 실행합니다. Store 이외의 방법으로 설치하면 artifactize-tools 명령도 함께 설치됩니다. stdout에 텍스트나 JSON을 출력하고, 도구가 실패하면 stderr에 오류를 남기고 1로, 사용법이 잘못되면 2로 종료합니다. artifactize tools --help가 도구 목록을 보여 주며, artifactize tools check는 이와 달리 선언된 리뷰 도구를 점검합니다. 하위 명령별 범위 규칙과 제한은 artifactize-tools에 있습니다.

Agent 스트리밍과 Runtime 로그

verify SELECTOR --watch는 Run을 제출한 직후부터 진행 상황을 보여 주고, run watch RUN_ID로는 나중에 진행 상황 보기를 시작할 수 있습니다. 둘 다 --json과 상관없이 JSON 줄을 바로바로 내보냅니다. kind: update 이벤트에는 실시간 상태와 개수가, kind: eval_result 이벤트에는 저장된 요청의 간단한 결과가, kind: outcome 이벤트에는 Run의 최종 검증 결과가 담깁니다. --watch와 --wait는 함께 쓸 수 없습니다. 지켜보는 명령은 Run 결과에 맞는 종료 코드로 끝나며, 중단하면 130으로 끝나고 지켜보기만 멈춥니다. 다시 연결하면 완료된 eval을 다시 보여 줄 뿐, 지난 이벤트를 그대로 재생하지는 않습니다. 자세한 내용이 필요하면 결과의 next_cursor를 MCP verify_result에 넘겨 다음 내용을 읽거나 저장된 Run을 살펴보세요.

Runtime eval이 실패했을 때:

artifactize request logs REQUEST_ID --stream stderr --tail 30
artifactize request logs REQUEST_ID --stream stdout --start 100 --end 150
artifactize request logs REQUEST_ID --search 'failure' --tail 10
artifactize config graph INPUT_ARTIFACT --impact --json

로그 조회 결과에는 전체 감사 기록 대신 로그 보존 여부와 원래 줄 번호가 담깁니다. tail은 기본으로 스트림마다 조건에 맞는 마지막 50줄을 돌려줍니다. 범위 조회는 스트림마다 최대 200줄과 제한된 바이트만 돌려주고, 이어서 볼 위치를 next_start로 알려 줍니다. tail과 범위 조회는 함께 쓸 수 없습니다. search는 1–2048바이트의 문자열을 대소문자를 구분해 그대로 찾습니다. 원래 2048바이트가 넘는 줄은 clipped로 표시하고 앞뒤 일부만 보여 줍니다. Runtime 원본 스트림 전체는 저장된 감사 기록의 128 KiB 한도를 넘는 뒷부분까지 Run 출력에 남습니다. prune은 이 원본 로그를 지우지 않으며, 정해진 주기로 지우는 기능도 없습니다. 원본 로그가 없거나 이전 버전 또는 원격 실행의 감사 기록만 남아 있으면 그 상태를 분명히 표시합니다. 공통 Runtime 보존 레퍼런스를 보세요. 공통 증거와 이벤트 스키마, 클라이언트 전달 제한은 MCP 집중 진단에 있습니다.

도구 진단

artifactize tools check                         # every Agent/Human eval's scope
artifactize tools check app/review              # same as --eval app/review
artifactize tools check --artifact app --audience agent
artifactize tools check --execute --artifact app --audience agent --tool read --args '{"path":"README.md"}'
artifactize tools check --execute --artifact app --audience human --tool inspect
artifactize tools check --execute --eval app/review --tool coverage_app --args '{}'

tools check는 선언의 유효성, 실행 파일이 있는지, 범위가 정해진 argv 인자와 선언된 실행 경로를 확인한 뒤 범위, 스키마, 도구별 준비 상태를 JSON으로 출력합니다. 기본으로는 정적으로만 확인하므로 프로젝트 도구나 fingerprint 스크립트를 실행하지 않고 상태나 출력 폴더도 만들지 않습니다. 위치 인자 선택자나 --eval은 Agent/Human eval 하나를 고르며, --artifact나 --audience와 함께 쓸 수 없습니다. 실제로 실행하려면 --tool을 지정하고, eval 선택자를 쓰거나 --artifact와 --audience를 함께 지정해야 합니다. --artifact를 쓰면 짧은 동작 이름과 공개된 이름을 모두 받으며, 범위는 그 Artifact 하나입니다. eval을 쓰면 그 eval이 공개하는 이름(<tool>_<artifact>)으로 도구를 지정합니다. 도구는 그 eval의 범위에서 실행되므로, 인자가 다른 Artifact를 가리키는 도구도 그 eval의 리뷰에서처럼 실행됩니다. --args는 Agent 실행에서만 쓸 수 있고, 생략하면 Agent 도구는 {}를 받습니다. Human 스키마는 빈 객체만 받고, Human 명령에는 임의의 인자를 넘길 수 없습니다. --execute를 쓰면 보고서의 result에 도구의 응답이 함께 담깁니다. content가 들어 있고, 도구가 실패하면 isError: true이며 종료 코드는 1입니다. 점검은 Run, 판정, 캐시 항목을 만들지 않습니다. Agent 호출은 작성자의 환경에서 별도의 임시 출력 폴더(실행 뒤 삭제)를 쓰고, Human 호출은 리뷰어의 실제 환경을 씁니다. 종료 코드는 준비 완료나 성공이면 0, 선언·사전 점검·도구·정리 실패면 1, 호출이 잘못되면 2입니다. --repo, --state-dir, --json을 받으며, --json이 없어도 보고서는 JSON입니다.

Run 목록

run list [--repo-only | --all]은 저장된 Run을 최신순으로 텍스트 표로, --json이면 JSON 배열로 보여 줍니다. 기본 대상은 정규화한 --repo 경로(생략하면 현재 디렉터리)입니다. --repo-only는 이 기본값을 명시하고, --all은 공유 상태의 모든 저장소를 포함합니다. --limit N(기본 50)과 --offset N(기본 0)은 각각 0–4294967295 범위로, 걸러 낸 결과를 페이지로 나눕니다. 범위를 벗어난 값을 지정하면 종료 코드 2로 끝납니다. 각 행에는 Run ID, 저장소, 생성·완료 시각, 상태, 판정과 상태별 요청 수(해당 상태가 없으면 0), Run의 코멘트(있을 때)가 나옵니다. run list는 손상된 기록을 확인하지 않으며, 손상된 기록과 그 이유는 status와 run show가 알려 줍니다. 상태 문제 해결을 보세요. 읽기만 하므로 프로젝트 코드를 실행하지 않고, 없는 상태를 만들지 않으며, 저장소가 지금 남아 있지 않아도 됩니다. 별도의 history 명령은 없습니다.

Config graph

config graph [ARTIFACT]는 기본으로 프로젝트 전체를 보여 주고, ARTIFACT를 주면 순환으로 묶인 Artifact까지 포함해 그 Artifact에 필요한 범위를 보여 줍니다. --impact는 그 결과를 쓰는 하위 Artifact와 각 Artifact가 쓰는 입력도 포함합니다. 이는 구조상 영향이 미칠 수 있는 범위를 넉넉하게 잡은 것이지, 재사용 키를 정확히 예측한 것은 아닙니다. MCP config_graph에서도 Artifact나 eval을 하나 또는 여러 개 골라 같은 정의를 볼 수 있습니다. 실제로 무엇을 실행하고 재사용할지는 status로 확인하세요. 텍스트 출력에는 태그와 파일 종류 표시가 붙은 Artifact, eval, 구성 요소, 입력에서 사용처로 가는 관계가 나옵니다. 전체 JSON에는 정해진 정적 Artifact/eval 정의(프로필, payload, 스키마, 도구 뷰), 태그, 부분·지시문·argv 관계 정보, 순환 표시, 그리고 서로 의존하는 Artifact 묶음인 강한 연결 요소(SCC)가 의존성 순서대로 들어 있습니다. Artifact 항목에는 kind(file, folder, aspect, graph)와 작업 공간 기준 대상 path가 있습니다. status도 파일 종류와 경로를 보여 주며, Monitor는 이를 화면에 보여 줍니다. 강한 연결 요소의 ID는 전체 그래프를 기준으로 매기므로, 일부만 보여 주면 번호가 띄엄띄엄 나올 수 있습니다. config check는 프로젝트 코드를 실행하지 않고 선언이 유효한지 확인하며, JSON 출력에는 Artifact와 eval 개수를 담습니다. 출력 형식은 텍스트와 전체 JSON 두 가지이며, plan, --compact, --full은 지원하지 않습니다. 예전의 최상위 graph 명령은 도움말에 나오지 않으며, 실행하면 graph moved to "artifactize config graph"를 출력하고 2로 종료합니다.

Human 요청

claim, unclaim, tool, submit은 기본 리뷰어 이름으로 $USER 값을 사용하며, 값이 없으면 Linux와 macOS에서는 $LOGNAME, Windows에서는 %USERNAME% 값을 사용합니다. 모두 없으면 --reviewer NAME을 주세요. --reviewer NAME으로 동작마다 같은 리뷰어를 직접 지정할 수도 있습니다. 리뷰어 이름은 계정 인증이 아니라 담당자를 구분하는 데 쓰이며, 같은 요청을 여러 리뷰어가 겹쳐 처리하지 않도록 로컬 잠금을 겁니다. 요청을 맡은 사람만 도구를 실행하고, 제출하고, 담당을 해제할 수 있습니다. request claim은 담당 정보를, request unclaim은 해제한 담당 정보를 출력합니다. 다른 리뷰어가 맡았거나 더 이상 대기 중이 아닌 요청의 담당을 해제하려 하면 종료 코드 2로 끝납니다. 도구 이름은 <operation>_<artifactId> 형식이며, 호출할 때 임의의 인자를 넘길 수 없습니다. 텍스트 출력은 캡처한 텍스트나 실행 알림을 보여 주고, --json은 도구 결과를 출력합니다. 도구가 실패하면 2로 종료하며 판정을 만들어 내지 않습니다.

제출하려면 --verdict GREEN|RED가 필요합니다. --fields와 --fields-file은 함께 쓸 수 없습니다. 둘 중 하나로 추가 결과 필드만 담은 JSON 객체를 넘기며, 판정은 이 객체에 넣지 않습니다. 생략하면 {}입니다. 파일은 일반 파일이어야 하고, 필드와 전체 결과는 256000바이트까지입니다. JSON, 스키마, 리뷰어 이름, 판정이 잘못되면 2로 종료하며, 요청은 수정 후 다시 제출할 수 있는 상태로 남습니다. 제출에 성공하면 RED여도 0으로 종료하며, 별도의 검증 과정을 시작하지 않습니다.

도구를 실행하거나 제출을 저장하기 전에 선언과 리뷰한 파일을 다시 확인합니다. 요청을 기록한 뒤로 eval의 선언이나 범위가 바뀌었거나, fingerprint가 바뀌었거나 계산할 수 없으면 요청은 판정 없이 ERROR 처리되고 명령은 종료 코드 2를 반환합니다. 오류 코드는 INPUT_CHANGED이며, fingerprint를 계산할 수 없을 때만 FINGERPRINT_RECHECK_FAILED입니다. 새 요청을 받으려면 verify를 다시 실행하세요.

이미 맡은 요청에 같은 리뷰어로 request claim을 다시 실행해도 기존 담당 정보를 돌려주고 0으로 종료하므로, 담당 지정은 반복해도 안전합니다. 제출은 한 번만 받으며, 다시 제출하면 종료 코드 2로 끝납니다. 명령이 중단되는 등 제출 결과가 불확실하면 다시 제출하기 전에 request show로 요청을 확인하세요.

Agent 세션

읽기. REF는 ref, 요청 ID(run-FiVNCV-1), sessionId 중 하나입니다.

artifactize session show run-FiVNCV-1
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · codex gpt-6-luna (reasoning max)
Reference: alice@laptop/34bb3c3a-…/run-FiVNCV/run-FiVNCV-1/e83bf374-…
Request run-FiVNCV-1 (Run run-FiVNCV), eval notes/review: GREEN

── System
You are an artifactize evaluator. …

── User (turn 1)
Eval: Review notes (notes/review)
Target Artifact: notes
Instruction: Check notes. …
Artifacts:
[{"name":"notes","role":"target","tools":["read_notes"]}]

── Assistant (turn 1)
[reasoning] Reading the notes
[tool call read_notes] {"path":"notes.md"}

── User (turn 2)
[tool result read_notes]
{"artifactId":"notes","lines":[{"number":1,"text":"notes: R1 holds.\n"}], …}

── Assistant (turn 2)
{"verdict":"GREEN","verdictFields":{}}

── Repair prompt (turn 3)
Your final response did not match the required schema: …

── Assistant (turn 3)
{"verdict":"GREEN","verdictFields":{"covered":["R1"]}}

── Result: {"covered":["R1"],"verdict":"GREEN"}

모델은 pass 또는 fail 스키마의 필드를 verdictFields 안에 담아 답하고, 결과에는 그 필드가 verdict와 나란히 들어갑니다. Agent 리뷰를 보세요.

텍스트 출력은 도구 결과를 2000자에서 자르고 reasoning은 요약만 보여 줍니다. --json은 {"reference", "file", "events"}를 출력합니다. 이 JSON에는 참조, 세션 파일, 저장된 이벤트 전체가 들어 있어 대화를 그대로 재생할 수 있습니다.

세션 요약

--summary는 세션 파일만 읽어 대화의 토큰 사용량과 도구 호출 수 등을 집계합니다. 턴(provider 요청)별 토큰 수와 합계, 도구별 호출 수와 실패 수, follow-up, 백엔드, 모델, 시간 범위가 나옵니다. 오류를 반환했거나, 예산 한도·시간 제한·리뷰 종료 때문에 실행하지 못한 호출을 실패한 호출로 셉니다.

artifactize session show run-FiVNCV-1 --summary
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · codex gpt-6-luna (reasoning max)
Reference: alice@laptop/34bb3c3a-…/run-FiVNCV/run-FiVNCV-1/e83bf374-…
Request run-FiVNCV-1 (Run run-FiVNCV), eval notes/review: GREEN
Time: 2026-10-06T09:14:02.118604115Z to 2026-10-06T09:16:41.502330019Z (159.4 s)
Turns: 5 · follow-ups: 1
Tokens: input 21410 · output 1318 · cache read 15872 · reasoning 704
  turn 1: input 3920 · output 212 · cache read 0 · reasoning 128
  turn 2: input 4310 · output 260 · cache read 3840 · reasoning 160
  turn 3: input 4402 · output 96 · cache read 4224 · reasoning 64
  follow-up 1, turn 1: input 4366 · output 410 · cache read 3840 · reasoning 224
  follow-up 1, turn 2: input 4412 · output 340 · cache read 3968 · reasoning 128
Tool calls: 3 (1 failed)
  read_notes: 2
  search_notes: 1 (1 failed)

여러 번 시도한 턴에는 (2 attempts)처럼 시도 횟수가 붙습니다. 토큰 수는 그 턴의 각 시도에서 provider가 보고한 값을 합산한 것이며, 한 번도 보고되지 않은 항목은 생략합니다. --json은 같은 내용을 객체 하나로 출력합니다. backend, model, reasoning, startedAt, endedAt, durationMs, followUps, turns(각 턴마다 follow-up에 대한 답이면 followUp, 그리고 turn, attempts, tokens), tokens, toolCalls ({"read_notes": {"calls": 2, "failed": 0}, …}), sessionId, requestId, reference가 들어 있습니다.

follow-up으로 이어서 묻기.

artifactize session send run-FiVNCV-1 "Which line shows R1, and does it still hold?"
Session e83bf374-5136-484c-8d2f-2ce38ee4ca57 · follow-up 1 · codex gpt-6-luna (reasoning max) · files changed since this review

notes.md line 1 says R1 holds, but it now reads "R1 fails", so the verdict would change.

헤더에는 follow-up 번호와 리뷰의 백엔드, 모델, reasoning이 표시됩니다(session show와 같은 정보입니다).

--json을 주면 send는 {"reference", "sessionId", "requestId", "send", "filesChanged", "answer", "usage"}를 출력합니다. send는 follow-up 번호, filesChanged는 리뷰한 입력이 바뀌었는지(알 수 없으면 null), answer는 답변 텍스트, usage는 시도별 토큰 수입니다.

follow-up은 저장된 대화를 같은 모델과 현재 프로젝트 도구로 이어 갑니다. 답변은 일반 텍스트이며, 기록된 판정, 결과, 재사용에는 영향을 주지 않습니다. 리뷰한 입력이 바뀌었으면 헤더에 경고가 나옵니다. 질문마다 프로필의 예산이 새로 적용되며, 한 세션에 보낸 질문은 차례대로 처리합니다. follow-up을 저장하는 방식은 follow-up 재생 레퍼런스를 보세요.

다른 머신이나 다른 상태의 참조를 주면 그 대화가 저장된 위치를 알려 주고 실패합니다. 예를 들면 Session e83bf374-… lives in alice@laptop's state 34bb3c3a-…; this is bob@desk's state 5d0e…입니다. 오래된 대화를 자동으로 정리하는 과정에서 세션이 지워졌으면 was removed by the session GC라는 안내가 나오고, 처음부터 저장하지 않은 세션에는 was not saved라는 안내가 나옵니다. 이런 경우, 아직 실행 중인 요청에 session send를 쓴 경우, follow-up이 실패한 경우에 session show와 session send는 종료 코드 2로 끝납니다.

보관. 저장소가 크기 한도를 넘으면 오래된 대화부터 지웁니다. 한도와 이를 바꾸는 방법은 Agent 세션에 있습니다.

개인정보. 대화에는 리뷰어가 도구로 읽은 모든 내용(파일 내용 포함)과 리뷰어가 쓴 모든 내용이 들어 있습니다. 대화는 이 머신에 본인만 읽을 수 있는 파일로 저장하며, 팀 리뷰 저장소를 비롯해 어디에도 올리지 않습니다. follow-up은 리뷰의 매 턴과 마찬가지로 대화를 그 리뷰의 백엔드로 보냅니다. 저장하지 않으려면 "agentSessions": {"enabled": false}로 끄고, 이미 저장된 대화는 $STATE/agent-sessions를 지워서 없애세요.