대화형 화면 없이 Pi를 쓰는 방법은 세 갈래입니다. 한 번 실행하고 끝나는 print 모드, 구조화 이벤트를 받아 읽는 JSON 모드, 장기 실행 프로세스를양방향으로 제어하는 RPC 모드입니다. 셋 다 대화형과 같은 엔진을 공유하므로 도구·확장·세션 규칙이 동일하게 적용됩니다.

호출과 출력

pi --print "이 저장소를 요약해 줘"
git diff | pi --print "이 변경점을 리뷰해 줘"
pi --mode json "이 저장소를 점검해 줘" > events.jsonl

터미널 stdin·stdout에서는 --print나 --mode를 지정하지 않는 한 터미널 UI가 열립니다. 둘 중 어느 쪽이든 리디렉션되면 자동으로 print 모드를 사용합니다.

입력	동작
message	첫 프롬프트로 사용
@path	첫 프롬프트에 텍스트 파일이나 이미지 포함
pipe stdin	첫 프롬프트 앞에 내용 prepend
--	옵션 해석 중단 (-로 시작하는 프롬프트용)

옵션	동작
-p, --print	프롬프트 실행 후 최종 어시스턴트 텍스트를 stdout에 쓰고 종료
--mode text	텍스트 출력 (stdout가 터미널이면 UI 유지)
--mode json	JSONL 이벤트를 stdout에 쓴 뒤 종료
--mode rpc	stdin으로 JSONL 명령을 받고 종료 시까지 응답·이벤트를 stdout에 기록

자주 쓰는 CLI 옵션

모델·세션 관련 핵심만 모읍니다.

pi --model sonnet:high                 # provider/id와 thinking 접미사 지원
pi --thinking high --model gpt-5
pi --list-models "sonnet"              # 사용 가능 모델 검색 후 종료
pi --continue                          # 현재 폴더의 최근 세션
pi --session <path|id>                 # 파일이나 ID로 세션 열기
pi --fork <path|id>                    # 세션을 현재 폴더에 포킹
pi --no-session                        # 임시 실행(저장 안 함)
pi --tools read,grep,find,ls --print "리뷰해 줘"

pi --help와 각 명령의 --help가 설치본의 정확한 인터페이스입니다. 상위 help에는 로드된 확장이 등록한 옵션도 표시됩니다.

JSON 모드: 이벤트 스트림 읽기

pi --mode json "저장소 리뷰해 줘"

JSON 모드는 세션 헤더 하나, 이어서 세션 이벤트를 쓴 뒤 종료합니다. 스트림은 엄격한 JSONL 프레이밍을 따릅니다. 레코드마다 LF(\n)로 끝나므로 LF로만 분할하고 앞의 CR은 버리세요. Node.js readline은 유니코드 구분자도 줄로 인식하므로 맞지 않습니다. stdout를 지속적으로 읽어야 합니다 — 파이프 버퍼가 차면 Pi가 멈춥니다. stdout는 JSONL 전용이고 진단·로그는 stderr로 나갑니다.

기본적인 이벤트 흐름은 다음과 같습니다.

{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{"role":"user","content":"..."}}
{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_end","message":{"role":"assistant","...":"..."}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...],"willRetry":false}
{"type":"agent_settled","aborted":false}

판독 요령:

• message_end가 확정된 최종 메시지입니다. message_update의 delta만 실린 와이어 레코드로 스트리밍 텍스트를 재조립할 수 있습니다.
• agent_end는 저수준 실행 하나를 닫습니다. 자동 재시도·압축 복구·대기 메시지가 뒤따를 수 있습니다.
• Pi가 더 이상 자동으로 이어가지 않는 지점을 기다려야 한다면 agent_settled를 사용하세요.

RPC 모드: 프로세스 원격 제어

RPC 모드는 stdin으로 JSONL 명령을 받고 stdout으로 응답과 이벤트를 쓰는 양방향·장기 실행 프로토콜입니다. JSON 모드와 같은 이벤트 형태를 쓰지만 세션 헤더는 없습니다(현재 세션은 get_state로 조회). 외부 언어 연동이나 자식 프로세스 제어에는 저장소의 타입된 RpcClient 사용 예시(examples/rpc-client.ts)가 레퍼런스로 제공됩니다.

node examples/rpc-client.ts "이 저장소를 설명해 줘"

자동화에서의 신뢰 판정

print·JSON·RPC 모드는 대화형 신뢰 프롬프트를 띄울 수 없습니다. 보호된 프로젝트 자원이 있는데 저장된 판정이 없다면 defaultProjectTrust가 "always"일 때만 로드됩니다. 무인 실행에는 --approve/--no-approve로 명시적인 일회성 결정을 주는 것이 안전합니다.

어느 것을 쓸까

상황	선택
원오프 스크립트, 파이프라인 한 단계	print 모드
진행 과정(도구 호출, 스트리밍)까지 구조화해서 소비	JSON 모드
하나의 프로세스를 오래 유지하며 대화·제어	RPC 모드
앱 안에서 직접 에이전트 객체를 다룸	TypeScript SDK