CLI 사용하기

awr 명령줄 도구는 AWR 프로젝트의 완전한 관리 진입점입니다: 에이전트가 MCP를 통해 할 수 있는 모든 것을 터미널에서 할 수 있습니다 — 게다가 MCP가 노출하지 않는 프로젝트 관리 작업까지 가능합니다.

설치

두 패키지 채널 모두 동일한 Rust CLI와 MCP 서버를 설치합니다; 별도의 JavaScript나 Python SDK는 없습니다:

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

awr --version과 awr-mcp --version으로 확인하세요.

지원 대상은 macOS 15+(arm64 및 Intel), glibc 2.39+의 Linux(Ubuntu 24.04 기준선, x64 및 arm64), Windows x64입니다. npm 런처는 Node 22.14+가 필요하고 선택적 네이티브 패키지에 의존하므로 선택적 의존성을 활성화한 상태로 유지하세요; PyPI 런처는 Python 3.9+가 필요합니다. Linux에서는 ldd --version | head -n 1로 glibc를 확인하세요. Git은 Git에 바인딩된 연산에만 필요하며, SQLite는 번들로 포함됩니다. 첫 프로젝트 워크스루는 빠른 시작을 참조하세요.

모든 명령의 형태

문서 전반의 CLI 예제는 공통 접두사를 공유합니다:

awr --project /absolute/project --json <command>

--project는 프로젝트 루트를 가리키고, --json은 stdout을 하나의 기계 판독 가능한 JSON 객체로 전환합니다(자세한 내용은 아래). 출력을 직접 읽을 때는 --json을 빼세요 — 기본 사람용 출력은 의도적으로 제한되어 있습니다: status는 최대 하나의 현재 제안을 보여주고 ready는 최대 10개 항목을 나열합니다.

프로젝트 상태 확인

status가 첫 번째 확인 지점입니다. 기본 action 뷰는 현재 이어할 작업, 클레임 가능한 작업, 대기, 실제 블로커, 이력 요약을 보여줍니다:

awr --project /absolute/project status --view full --branch main

--view action/full/summary — 기본값은 action; full은 레거시 전체 구조를 제공합니다.
--branch NAME_OR_ID — 기본 브랜치 대신 이름, 내부 ID 또는 main으로 브랜치를 읽습니다. 읽기를 위해 브랜치를 선택해도 기본 브랜치, 세션, 클레임, Git 체크아웃은 변경되지 않습니다.

ready는 진단, 클레임 정보, 잘림 힌트와 함께 픽업 가능한 작업 항목을 나열합니다. --limit은 기본값 10이며 1부터 100까지 받습니다; --branch도 여기서 동작합니다:

awr --project /absolute/project ready --limit 25

작업 항목 읽기

work show는 한 항목의 전체 — 태스크, 인수 기준, 의존성, 결정, 증적, 출처 — 를 보여줍니다. --source-sha SHA는 특정 소스 리비전 기준으로 읽고, --branch는 다른 브랜치에서 읽습니다:

awr --project /absolute/project work show W-123 --source-sha abc123

search는 프로젝트 전체에서 항목을 찾습니다. 쿼리 텍스트는 위치 인자이고, --type, --status, --work, --limit이 결과를 좁힙니다:

awr --project /absolute/project search "payment retry" --type work --limit 20

태스크를 위한 컨텍스트 컴파일

context compile은 L1 실행 컨텍스트 — 태스크를 위한 예산 제한 작업 세트 — 를 완전성, 갭, 출처, Context 해시와 함께 조립합니다:

awr --project /absolute/project context compile --work W-123

이 모든 것은 선택 사항입니다: --session과 --detached는 세션 바인딩을 제어하고, --agent, --intent, --budget은 컴파일을 조정하며, --goal, --path, --tag는 반복 가능하고, --source-sha는 특정 소스 버전을 기준으로 컴파일하며, --checkpoint와 --after-revision은 사용자 정의 기준선을 설정하고 서로 배타적입니다. --branch ID는 다른 브랜치에서 일반 컨텍스트 기준선을 사용합니다 — 이는 branch context와 다른 의미로, 후자는 기본 브랜치를 전환하지 않고 명명된 브랜치가 포크된 이후의 증분을 컴파일합니다:

awr --project /absolute/project branch context feature-x --work W-123

기본 텍스트 출력은 완전한 인수 기준과 하드 규칙이 보존된 예산 제한 실행 컨텍스트입니다. 필수 갭이 있으면 JSON 결과는 error.code=ContextIncomplete와 함께 ok=false가 되고, 하드 사실이 예산을 초과하면 BudgetExceeded가 됩니다 — 사실이 조용히 잘리는 일은 절대 없습니다.

작업 진행

작업 항목은 work 서브커맨드를 통해 상태를 변경합니다:

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

block, unblock, cancel, reopen에도 같은 형태가 적용되며, --next-action, --summary, --blocker가 해당 상세 정보를 담습니다. 완료는 JSON 파일에서 인수 기준과 증적을 바인딩하고 성공 시 이 세션의 클레임을 해제합니다:

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

이벤트와 증적 기록

event append는 프로젝트 로그에 기록합니다:

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

선택적 플래그: --work, --session, --branch, --importance(기본값 normal), --payload FILE(JSON 값 파일, 생략 시 {}). 기본 출력은 ID, 타입, 짧은 요약, 버전을 보여주며 — 페이로드를 에코하지 않습니다; event show --full로 이벤트를 명시적으로 펼치세요. work.completed 같은 예약된 도메인 이벤트는 위조할 수 없습니다; 그것들은 상태 변경 명령에서만 나옵니다.

evidence add는 JSON 입력 파일로부터 증적을 기록합니다:

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

입력 필드에는 work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope, verified_at가 포함됩니다. 성공적인 쓰기는 저장된 레코드와 event_id를 반환하지만, 기록은 실행이 아닙니다: validation_basis=caller_supplied_bindings는 AWR이 여러분이 제출한 바인딩을 저장했다는 뜻이지 — 명령을 실행했거나 비즈니스 인수가 통과했다는 뜻이 아닙니다. evidence show는 레코드의 요약 읽기 뷰를 제공하며, 쓰기 영수증이 아닙니다.

경로 및 크기 규칙: 증적 입력과 이벤트 페이로드의 상대 경로는 --project 루트 기준으로 해석되고, 완료 입력의 상대 경로는 프로세스의 현재 디렉터리 기준으로 해석되므로 자동화에서는 절대 경로를 사용하세요. 증적 입력과 이벤트 페이로드 파일은 1 MiB로, 완료 입력은 64 KiB로 제한됩니다.

리비전과 낙관적 동시성

쓰기는 --expected-revision R을 받으며, R은 여러분이 관찰한 가장 최근의 project_revision입니다. 프로젝트가 진행되었다면, 쓰기는 다른 사람의 작업을 조용히 덮어쓰는 대신 RevisionConflict로 실패합니다 — status로 다시 읽고 새 리비전으로 재시도하세요. 세 가지 버전 번호가 출력에 나타나며 서로 교환할 수 없습니다: revision은 객체의 버전, source_revision은 소스의 버전, project_revision은 프로젝트 상태의 버전입니다.

쓰기가 중단되거나 부분적으로 적용되었다면, 다음에 무엇을 할지 결정하기 전에 제안, 이벤트, 세션, 현재 리비전을 확인하세요 — 프로세스 실패 후에 맹목적으로 재시도하지 마세요. 두 가지 워크스페이스 오류는 언급할 가치가 있습니다: WorkspaceConflict(awr workspace에서 발생)는 양쪽이 같은 추적 파일을 편집했고 아무것도 자동 머지되지 않았다는 뜻이고, WorkspaceContended는 publish 또는 drop이 세 커밋 연속으로 선점되었다는 뜻이며, 해결책은 단순히 같은 명령을 다시 실행하는 것입니다.

JSON 출력, 오류, 종료 코드

--json을 사용하면 성공한 명령은 stdout에 정확히 하나의 JSON 객체를 출력합니다. 오류는 stderr에 타입이 지정된 JSON입니다:

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

두 스트림을 분리해서 파싱하세요 — 2>&1로 합친 후 결합된 텍스트를 파싱하지 마세요. code와 details가 결정을 위한 기계 판독 가능한 근거이고, message는 사람을 위한 것입니다. --json은 알려진 서브커맨드 앞이나 뒤에 올 수 있습니다; 알 수 없는 최상위 명령에 대해 JSON 오류를 받으려면 명령 앞에 두세요. 종료 코드:

0 — 성공(--help와 --version도 포함).
1 — 도메인 오류(stderr에 타입이 지정된 오류), stdout에 부분적이고 검사 가능한 본문이 있을 수 있음; 구현되지 않은 최상위 명령에 대한 Unsupported도 포함.
2 — 누락되거나 잘못된 인자 또는 알 수 없는 중첩 서브커맨드; --json 모드에서는 InvalidInput.

CLI가 끝나고 MCP가 시작되는 지점

CLI와 MCP 서버는 동일한 도메인 상태를 노출합니다: 공유 작업 및 컨텍스트 도구에 대해, 둘 다 동일한 프로젝트, 브랜치 선택, 인덱싱된 소스, 매개변수 아래에서 동일한 식별자, 버전, 인수 기준, 의존성, 진단, 갭을 반환합니다. 차이는 자세(posture)입니다:

CLI는 완전한 프로젝트 관리 진입점이며, 읽기가 재구성 가능한 데이터베이스 프로젝션을 갱신할 수 있습니다(source_refresh).
MCP 읽기 도구는 엄격하게 읽기 전용입니다(read_only=true). 소스가 변경되었다면, MCP 읽기는 갱신하는 대신 오래된 스냅샷을 SourceStale로 거부합니다; awr source reindex를 실행하고 다시 읽으세요.
MCP stdio는 에이전트 클라이언트를 위한 고정된 도구 카탈로그를 노출합니다(공유 HTTP 서비스는 프로젝트 디렉터리 도구를 추가합니다); 그 카탈로그를 넘는 관리 작업은 CLI에 남습니다.

실무에서는 터미널에서 설정, 관리, 재인덱싱, 임시 조사를 수행하고, 에이전트 클라이언트가 세션 중에 MCP 도구를 호출합니다. 에이전트 측은 MCP 도구를, 문제가 발생하면 문제 해결을 참조하세요.