명령

zeropty CLI 의 모든 명령과 옵션이에요. 같은 명령이 소켓과 임베딩 API 에서도 그대로 돼요.

CLI 빠르게 보기

zeropty new-session -d -s work -x 220 -y 80 -c ~/proj "$PWD/dist/claude-zeropty"   # 서버가 없으면 띄워요
zeropty capture-pane -p -e -S -200 -t '=work:'    # 화면 + 스크롤백 200줄, 색 포함
zeropty wait-pane -t '=work:' -m '>' -q 1000 -T 60000   # '>'가 보이고 1초 조용할 때까지 (최대 60초)
zeropty send-keys -t '=work:' -l 'hello' && zeropty send-keys -t '=work:' Enter
zeropty attach -t work                            # 사람이 붙어서 보기. Ctrl-b d로 떼기
zeropty attach -r -t work                         # 읽기 전용 (q 또는 Ctrl-c로 떼기)
zeropty kill-session -t '=work:'

도움말과 버전. zeropty --help(또는 -h, help)는 명령과 옵션 목록을, zeropty help <명령>은 그 명령의 사용법과 하는 일, 이 문서의 해당 절 링크를 표준 출력에 내고 종료 코드 0으로 끝나요. 줄임말(help send)도 돼요. 프로그램이 직접 답해서 서버가 없어도 되고, 서버를 띄우지도 않아요. zsh 함수와 bash builtin에서도 같아요. zeropty -V(또는 --version)는 CLI 자신의 버전을 출력해요(실행 중인 서버의 버전은 zeropty display -p '#{version}'). 무엇이 호환 범위인지는 버전 정책, 바뀐 내용은 Changelog에 있어요. 옵션별 설명은 아래 명령 레퍼런스에 있어요.

zeropty --help     # 명령 목록 (종료 코드 0)
zeropty help send-keys   # 명령 하나: 사용법, 하는 일, 문서 링크 (없는 명령이면 종료 코드 2)
zeropty -V         # zeropty X.Y.Z (--version도 같아요)
zeropty            # usage: zeropty serve | <tmux command> ...  (표준 에러, 종료 코드 2)

명령 레퍼런스

괄호 안은 tmux와 같은 줄임말이에요. 옵션 뒤의 <값>은 값을 받는 옵션이에요.

세션

명령	옵션	하는 일
new-session (new) [명령]	-d -s <이름> -x <열> -y <행> -c <폴더> -e <변수=값> -A -P -F <포맷>	세션을 만들어요. 명령이 없으면 $SHELL(없으면 /bin/sh)이에요. 크기 기본값은 80×24이고, 이름이 없으면 지금까지 만든 세션 수(0, 1, ...)를 써요. -A는 같은 이름이 있으면 그대로 두고 성공해요. -P는 새 세션 정보를 출력해요(-F로 형식 지정, 기본 이름:). -e는 여러 번 쓸 수 있어요. -n -E -D -X는 창·클라이언트용이라 받아만 둬요
has-session (has)	-t	세션이 있으면 0, 없으면 1 (can't find session: 이름)
kill-session	-t -a	세션의 프로세스 그룹에 SIGHUP을 보내고, 2초 뒤에도 남은 프로세스는 SIGKILL해요. -a는 -t 세션을 뺀 나머지 전부예요. -C는 받아만 둬요
list-sessions (ls)	-F <포맷>	세션 목록. 기본 출력은 tmux와 같은 이름: 1 windows (created ...)예요
rename-session (rename) <새 이름>	-t	이름을 바꿔요. 빈 이름, :·.이 든 이름, 이미 있는 이름은 오류예요
resize-window (resizew), resize-pane (resizep)	-t -x <열> -y <행>	화면 크기를 바꿔요. 프로그램은 SIGWINCH를 받아요
pipe-pane (pipep) [명령]	-t -o -O	세션 출력을 명령의 입력으로 계속 보내요(tmux의 -O가 기본). 명령 없이 부르면 닫혀요. -o는 이미 열려 있으면 닫기만 해요. 명령이 못 받는 출력은 8MB까지 기다리고 넘치면 버려요. 세션을 다른 프로세스로 옮기면 닫혀요
kill-server		모든 세션에 SIGHUP을 보내요. 독립 서버는 프로세스도 끝나요. 임베디드 엔진은 세션만 끝나고 계속 돌아요

프로그램이 끝나면 세션도 끝나요(tmux의 remain-on-exit 꺼짐과 같아요).

서버는 자신을 띄운 프로세스(서버를 띄우는 첫 명령: new-session, pull-sessions, zeropty serve)의 환경을 그대로 가져요(tmux와 같아요). 세션은 new-session을 실행한 셸의 환경이 아니라 그 환경에 set-environment -g와 -e를 적용한 것을 받아요. restart-server는 그 명령을 실행한 셸에서 새 서버를 띄워서, 이후 세션은 그 셸의 환경을 받고 set-environment -g로 넣은 값은 사라져요(다시 넣어야 해요). 실행 중인 세션은 자기 환경을 그대로 가져요. 세션 안의 프로그램이 받는 환경: TERM=xterm-256color, COLUMNS/LINES, ZEROPTY_SESSION(세션 이름), ZEROPTY_COLS/ZEROPTY_ROWS, ZEROPTY_SIZE_FILE(shim이 읽는 창 크기 파일), ZEROPTY_TTY_ID(어느 파일이 세션의 터미널인지, shim용). TMUX, TMUX_PANE은 지워요(tmux 안에서 서버를 띄웠어도 세션은 tmux 안이 아니에요).

키 보내기

명령	옵션	하는 일
send-keys (send) <키>...	-t -l -H -N <횟수>	키를 보내요. 인자마다 키 이름이면 그 키의 바이트를, 아니면 글자 그대로를 보내요. -l은 키 이름을 해석하지 않고 글자 그대로 보내요. -H는 인자를 16진수 바이트로 읽어요(-H 41 42 0a는 AB + 줄바꿈). -N은 전체를 그 횟수만큼 반복해요
paste-buffer (pasteb)	-t -b <버퍼> -d -p -r -s <구분자>	버퍼 내용을 키처럼 보내요. 줄바꿈은 \r로 바꿔 보내요(-r이면 그대로, -s로 구분자 지정). -p는 프로그램이 bracketed paste를 켰으면 감싸서 보내요. -d는 보낸 뒤 버퍼를 지워요

키는 PTY처럼 라인 디시플린을 거쳐요.

화면 읽기

명령	옵션	하는 일
capture-pane (capturep)	-t -p -e -J -N -S <줄> -E <줄> -b <버퍼> -q	화면을 텍스트로 읽어요. 읽기 직전에 밀린 출력부터 처리해서 늘 최신 화면이에요. -e는 색·글꼴 이스케이프 포함, -J는 줄바꿈으로 나뉜 줄을 이어 붙이고, -N은 줄 끝 공백을 남겨요. -S/-E는 tmux와 같은 줄 번호예요(0이 화면 첫 줄, 음수가 스크롤백, -는 끝까지). -p가 없으면 tmux처럼 화면을 버퍼(-b, 없으면 buffer0)에 넣고 아무것도 출력하지 않아요
display-message (display) [포맷]	-t -p -F <포맷>	포맷 변수를 채워서 출력해요. 예: display-message -p -t '=work:' '#{cursor_x},#{cursor_y}'

기다리기와 찾기

tmux에는 없는 zeropty 명령이에요. 에이전트가 끝났는지, 어느 세션이 입력을 기다리는지를 폴링 없이 알아요.

명령	옵션	하는 일
wait-pane	-t -m <글자> -q <ms> -T <ms>	-m은 그 글자가 화면에 나타날 때까지(이미 있으면 바로), -q는 세션이 그 시간 동안 아무것도 출력하지 않을 때까지 기다려요. 둘 다 주면 둘 다 만족할 때 답해요. -T가 지나면 종료 코드 1(wait-pane: timed out), 기다리는 중에 세션이 끝나도 1(wait-pane: session ended)이에요
grep-panes <글자>	-S <줄>	모든 세션의 화면에서 글자를 찾아 세션: 줄로 보여요. -S는 capture-pane -S처럼 스크롤백까지 찾아요(-S -100). 세션 이름순이고, 없으면 종료 코드 1이에요(grep처럼)

• wait-pane은 서버가 출력이 올 때만, 그 출력이 바꾼 행만 확인해요. 글자는 행 단위로 찾아요(줄바꿈으로 나뉜 글자는 못 찾아요).
• 같은 연결의 다음 명령은 wait-pane의 답 뒤에 처리돼요. client/zeropty.mjs는 wait-pane마다 연결을 따로 열어서 다른 명령이 막히지 않아요.
• 세션이 마지막 출력을 내자마자 끝나면, 엔진이 그 출력을 확인하기 전에 세션 종료를 먼저 알려 wait-pane: session ended(종료 코드 1)로 끝날 수 있어요(알려진 문제). 기다리는 글자가 나온 뒤에도 세션이 살아 있게 하세요. 예: sh -c 'make; echo build done; exec cat'
• 임베디드 엔진의 함수 호출로는 wait-pane을 쓸 수 없어요(답을 미룰 루프가 없어서). 서버 플러그인을 켜면 소켓으로는 돼요. Rust 호스트는 Engine::wait_start·wait_check를 직접 써요(examples/polled.rs).

버퍼

명령	옵션	하는 일
load-buffer (loadb) <파일>	-b <버퍼>	파일 내용을 버퍼에 넣어요(기본 buffer0). 상대 경로는 명령을 보낸 쪽의 현재 폴더 기준이에요
paste-buffer		키 보내기를 보세요
capture-pane -b		-p 없이 쓰면 화면을 버퍼에 넣어요

보기 (attach)

명령	옵션	하는 일
attach-session (attach, a)	-t -r	지금 터미널로 세션에 붙어요. Ctrl-b d로 떼요. -r은 읽기 전용이고 q나 Ctrl-c로 떼요. -t가 없으면 세션이 하나일 때 그 세션에, 여럿이면 번호를 물어봐요

붙어 있는 동안 세션은 내 터미널 크기를 따르고, 떼면 원래 크기로 돌아와요. 여러 터미널이 한 세션에 붙을 수 있고, 크기는 마지막에 붙은 터미널을 따라요.

환경

명령	옵션	하는 일
set-environment (setenv) <변수> [값]	-g -u	이후에 만드는 세션에 줄 환경변수를 정해요. -u는 지워요. -g 없이는 tmux에서도 새 창에만 적용되는데, 세션에 새 창이 생기지 않으니 아무 일도 하지 않아요
show-environment (showenv)	-g	-g로 정한 변수를 보여요. 지운 변수는 -변수로 보여요

서버와 세션 옮기기

명령	옵션	하는 일
serve	--bind <소켓>	독립 서버를 직접 띄워요(보통은 new-session이 알아서 띄워요)
pull-sessions [이름...]	-s <소켓>	다른 서버의 세션을 이 서버로 가져와요(이름 없으면 전부)
push-sessions [이름...]	-s <소켓>	이 서버의 세션을 다른 서버로 보내요
restart-server		새 서버가 세션을 전부 넘겨받고 소켓 자리를 차지해요. 업그레이드에 써요

자세한 동작: 세션 옮기기. 서버끼리 쓰는 내부 요청 export-sessions, import-sessions: 소켓 프로토콜

플러그인

명령	옵션	하는 일
list-plugins		붙은 플러그인마다 한 줄: 이름: 상태 (api N) events=... commands=... access=... dropped=N. 상태는 running, stopped, failed (이유)예요
plugin-attach		소켓 연결을 플러그인으로 바꿔요. 소켓에서만 의미가 있어요
plugin-run <라이브러리.dylib>		C 플러그인 라이브러리를 별도 프로세스로 불러와 서버에 붙여요. 서버가 끝나면 같이 끝나요

플러그인이 더한 명령은 내장 명령처럼 CLI·소켓·임베디드에서 불러요. ZEROPTY_PLUGIN_DIR를 지정하면 zeropty serve가 그 디렉터리의 플러그인을 띄우고 끝나면 다시 띄워요. 지정하지 않으면(기본) 아무것도 실행하지 않아요. 디렉터리 지정이 그 안의 코드를 서버와 같은 사용자로 실행해도 된다는 동의라서 기본은 꺼 뒀어요(이 기능 전과 같은 동작). 붙이는 법과 프로토콜: 플러그인 API

진단

명령	하는 일
stats	엔진 카운터 한 줄: sessions, heap_bytes(할당기에 요청한 바이트), screen_bytes, live/frozen 화면 수, 읽기 횟수 등
mstats	할당기(mimalloc) 통계. 독립 서버에만 있어요(그 프로세스의 할당기를 세는 명령이라서요)
mem -t <세션>	화면 하나의 메모리 내역. 얼린 화면이면 frozen <바이트> B deep <true/false>