CLI 레퍼런스

purplemux는 한 바이너리를 두 가지 방식으로 사용합니다: 서버 시작 (purplemux / purplemux start)과, 실행 중인 서버에 말을 거는 HTTP API 래퍼 (purplemux <subcommand>). 짧은 별칭 pmux도 동일합니다.

한 바이너리, 두 역할

bin/purplemux.js의 디스패처가 첫 인자를 보고 결정합니다: 알려진 서브커맨드면 bin/cli.js로 라우팅, 그 외(또는 인자 없음)이면 서버를 시작합니다.

서버 시작

purplemux              # 기본
purplemux start        # 같은 동작, 명시적
PORT=9000 purplemux    # 커스텀 포트
HOST=all purplemux     # 모든 인터페이스 바인드

전체 env는 포트 & 환경변수 참고.

서버는 바인드된 URL, 모드, 인증 상태를 출력합니다:

  ⚡ purplemux  v0.x.x
  ➜  Available on:
       http://127.0.0.1:8022
       http://192.168.1.42:8022
  ➜  Mode:   production
  ➜  Auth:   configured

8022이 사용 중이면 경고 후 임의의 빈 포트로 바인드합니다.

서브커맨드

모든 서브커맨드는 실행 중인 서버를 필요로 합니다. 포트는 ~/.purplemux/port에서, 인증 토큰은 ~/.purplemux/cli-token에서 읽습니다 — 둘 다 서버 시작 시 자동으로 생성됩니다.

별도 표기가 없으면 출력은 JSON. --workspace와 -w는 호환됩니다.

tab create 패널 타입

-t / --type 플래그로 패널 타입을 선택합니다. 유효한 값:

-t 미지정 시 일반 터미널.

tab browser 서브커맨드

탭의 패널 타입이 web-browser일 때만, 그리고 macOS Electron 앱에서만 동작합니다 — 그 외에는 브리지가 503을 반환합니다.

예시

# 워크스페이스 찾기
purplemux workspaces

# ws-MMKl07 워크스페이스에 Claude 탭 생성
purplemux tab create -w ws-MMKl07 -t claude-code -n "refactor auth"

# 프롬프트 전송 (TAB_ID는 `tab list`에서)
purplemux tab send -w ws-MMKl07 tb-abc "Refactor src/lib/auth.ts to remove the cookie path"

# 상태 확인
purplemux tab status -w ws-MMKl07 tb-abc

# pane 스냅샷
purplemux tab result -w ws-MMKl07 tb-abc

# web-browser 탭 전체 페이지 스크린샷
purplemux tab browser screenshot -w ws-MMKl07 tb-xyz -o page.png --full

인증

모든 서브커맨드는 x-pmux-token: $(cat ~/.purplemux/cli-token)을 보내고, 서버는 timingSafeEqual로 검증합니다. ~/.purplemux/cli-token은 첫 서버 시작 시 randomBytes(32)로 생성되어 모드 0600로 저장됩니다.

~/.purplemux/를 볼 수 없는 다른 셸이나 스크립트에서 CLI를 구동해야 한다면 env로 직접 주입할 수 있습니다:

PMUX_PORT=8022 PMUX_TOKEN=$(cat ~/.purplemux/cli-token) purplemux workspaces

update-notifier

purplemux는 매 실행 시 update-notifier로 npm에서 최신 버전을 확인하고, 새 버전이 있으면 배너를 출력합니다. 끄려면 NO_UPDATE_NOTIFIER=1 또는 표준 update-notifier opt-out 설정을 사용하세요.

전체 HTTP API

purplemux api-guide를 실행하면 모든 /api/cli/* 엔드포인트의 완전한 HTTP API 레퍼런스(요청 본문과 응답 형태 포함)를 출력합니다 — curl 등 다른 런타임에서 직접 구동할 때 유용합니다.

다음으로

• 포트 & 환경변수 — 더 큰 env 표면 안에서의 PMUX_PORT / PMUX_TOKEN
• 아키텍처 — CLI가 실제로 통신하는 대상
• 문제 해결 — CLI가 "is the server running?"이라고 할 때