sw

name	sw
description	브라우저 자동화 CLI (스텔스 기능 포함). TRIGGER when: 웹 자동화, 브라우저 조작, 스크린샷, "sw", 폼 입력, 웹 스크래핑, 페이지 캡처, 로그인 자동화, 요소 클릭, 페이지 탐색 요청이 있을 때. DO NOT TRIGGER when: 일반 HTTP 요청(curl/wget), REST API 호출, 서버사이드 작업.

sw (Stealth Wright) — 스텔스 브라우저 자동화 CLI

설치 확인

which sw || echo "설치 필요"
sw --version 2>/dev/null || echo "버전 확인 불가"

설치가 안 되어 있으면:

# Homebrew
brew install kyungw00k/cli/sw

# 소스 빌드
git clone https://github.com/kyungw00k/stealth-wright.git
cd stealth-wright
go build -o build/sw ./cmd/sw
make install

핵심 명령어

탐색 (Navigation)

sw open <url>              # 브라우저 열고 URL로 이동
sw goto <url>              # 현재 세션에서 URL로 이동
sw go-back                 # 뒤로 가기
sw go-forward              # 앞으로 가기
sw reload                  # 페이지 새로고침
sw close                   # 브라우저 세션 닫기

스냅샷 & 스크린샷

sw snapshot                         # ARIA 트리 + 요소 ref 생성
sw screenshot                       # 스크린샷 저장
sw screenshot --annotate            # ref 번호가 오버레이된 어노테이트 스크린샷
sw screenshot --full-page           # 전체 페이지 스크린샷
sw screenshot --filename out.png    # 특정 파일명으로 저장
sw pdf [filename]                   # 페이지를 PDF로 저장

상호작용 — ref 기반 (snapshot 선행 필요)

sw click <ref>             # 요소 클릭 (예: sw click e5)
sw dblclick <ref>          # 더블클릭
sw hover <ref>             # 마우스 오버
sw fill <ref> <text>       # 입력 필드에 텍스트 입력
sw check <ref>             # 체크박스/라디오 체크
sw uncheck <ref>           # 체크 해제
sw select <ref> <value>    # 드롭다운 선택

상호작용 — semantic 로케이터 (snapshot 불필요)

sw click --role button --text "Submit"
sw click --label "닫기"
sw fill --label "Email" "[e-mail]"
sw fill --placeholder "검색어를 입력하세요" "query"
sw hover --role link --text "About"
sw check --label "로그인 상태 유지"

# 요소 탐색
sw find --role button
sw find --text "로그인"
sw find --label "이메일"
sw find --placeholder "비밀번호"

Semantic 로케이터 플래그

플래그	설명
--role <aria-role>	ARIA 역할: button, link, textbox, checkbox, heading 등
--text <string>	보이는 텍스트 (부분 일치)
--label <string>	aria-label 속성 (부분 일치)
--placeholder <string>	input placeholder (부분 일치)
--exact	정확한 문자열 매칭 요구

전역 옵션

플래그	기본값	설명
-s, --session <name>	default	세션 이름
-b, --browser <type>	chromium	브라우저: chromium, firefox, webkit
--headed	false	헤드 모드(화면 표시)
--stealth	true	스텔스 모드 활성화
--no-stealth	—	스텔스 모드 비활성화
--persistent	false	프로필 디스크 저장

시나리오별 사용법

1. 웹 페이지의 구조를 파악할 때 (ARIA snapshot)

페이지의 요소 구조를 파악하고 [ref=eN] 참조를 얻는 기본 워크플로우:

sw open https://example.com
sw snapshot

출력 예시:

- heading "Example Domain" [level=1] [ref=e1]
- paragraph [ref=e2]: This domain is for use in illustrative examples.
- link "More information..." [ref=e3]

이후 ref를 사용해 요소와 상호작용:

sw click e3           # "More information..." 링크 클릭
sw fill e1 "텍스트"   # heading에 텍스트 입력

2. 스크린샷을 찍어 시각적으로 확인할 때

sw open https://example.com

# 기본 스크린샷
sw screenshot

# 전체 페이지 스크린샷
sw screenshot --full-page

# 특정 파일명으로 저장
sw screenshot --filename result.png

3. 어노테이트 스크린샷으로 요소를 식별할 때 (멀티모달 AI용)

ref 번호가 각 요소 위에 오버레이된 스크린샷 — 멀티모달 AI 모델이 요소를 시각적으로 식별하는 데 유용:

sw open https://example.com
sw screenshot --annotate
# → 각 요소에 [e1], [e2], [e3] 등 ref 번호가 표시된 이미지 저장

어노테이트 스크린샷을 확인한 뒤 ref 번호로 바로 조작:

sw click e5
sw fill e2 "입력할 내용"

4. 로그인 폼을 자동으로 입력할 때

방법 A — snapshot + ref 기반:

sw open https://example.com/login
sw snapshot
# → - textbox "이메일" [ref=e1]
# → - textbox "비밀번호" [ref=e2]
# → - button "로그인" [ref=e3]

sw fill e1 "[e-mail]"
sw fill e2 "mypassword"
sw click e3

방법 B — semantic 로케이터 (snapshot 불필요):

sw open https://example.com/login
sw fill --label "이메일" "[e-mail]"
sw fill --placeholder "비밀번호" "mypassword"
sw click --role button --text "로그인"

5. ref 기반으로 특정 요소를 클릭할 때

sw open https://example.com
sw snapshot

# 링크 클릭
sw click e3

# 우클릭 (컨텍스트 메뉴)
sw click e3 right

# 더블클릭
sw dblclick e5

# 체크박스
sw check e7
sw uncheck e7

# 드롭다운 선택
sw select e4 "옵션값"

6. semantic 로케이터로 요소를 찾을 때

snapshot 없이도 ARIA 속성으로 요소를 직접 찾고 조작:

sw open https://example.com

# 모든 버튼 탐색
sw find --role button
# → ### Found 3 element(s)
# → - [ref=e3] <button> "로그인"
# → - [ref=e7] <button> "회원가입"
# → - [ref=e12] <button> "비밀번호 찾기"

# 텍스트로 탐색
sw find --text "로그인"

# label로 탐색
sw find --label "이메일 주소"

# 찾은 후 바로 조작
sw click --role button --text "로그인"
sw fill --label "이메일 주소" "[e-mail]"

7. 전형적인 AI 에이전트 워크플로우

open → snapshot → 요소 식별 → 상호작용 → 검증:

# 1. 브라우저 열기
sw open https://example.com

# 2. 구조 파악
sw snapshot

# 3. 어노테이트 스크린샷으로 시각 확인 (멀티모달 모델용)
sw screenshot --annotate

# 4. ref 또는 semantic으로 상호작용
sw fill e1 "검색어"
sw click --role button --text "검색"

# 5. 결과 검증
sw snapshot
sw screenshot

8. 다중 세션 관리

# 별도 세션으로 브라우저 열기
sw open https://site-a.com -s session-a
sw open https://site-b.com -s session-b

# 세션 목록 확인
sw list

# 세션 전환 (각 명령어에 -s 플래그 사용)
sw snapshot -s session-a
sw click e3 -s session-b

# 세션 닫기
sw close -s session-a
sw kill-all   # 모든 세션 종료

9. 상태 저장 및 복원 (로그인 세션 유지)

# 로그인 후 상태 저장
sw open https://example.com/login
sw fill --label "이메일" "[e-mail]"
sw fill --placeholder "비밀번호" "mypassword"
sw click --role button --text "로그인"
sw state-save ./login-state.json

# 다음 세션에서 로그인 상태 복원
sw open https://example.com
sw state-load ./login-state.json
# → 로그인 상태로 바로 사용 가능

출력 형식

snapshot 출력 (ARIA 트리)

- heading "페이지 제목" [level=1] [ref=e1]
- paragraph [ref=e2]: 본문 텍스트
- textbox "이메일" [ref=e3]
- textbox "비밀번호" [ref=e4]
- button "로그인" [ref=e5]
- link "비밀번호 찾기" [ref=e6]

[ref=eN] 형식의 참조값은 이후 sw click, sw fill 등 명령어에서 바로 사용 가능.

find 출력

### Found 3 element(s)
- [ref=e3] <button> "로그인"
- [ref=e7] <button> "회원가입"
- [ref=e12] <button> "비밀번호 찾기"

주의사항

• 스텔스 모드 기본 활성화: WebDriver 마커 숨김, 핑거프린트 스푸핑, WebRTC 누출 방지 등 봇 탐지 우회 기능이 기본으로 켜져 있음. 비활성화 시 --no-stealth 사용.
• 데몬 방식 동작: CLI와 브라우저 프로세스가 Unix 소켓을 통한 JSON-RPC 2.0으로 통신. sw open 시 데몬이 자동 시작됨.
• ref는 snapshot 후 유효: [ref=eN] 참조는 마지막 sw snapshot 기준. 페이지 변경 후엔 다시 snapshot 필요.
• semantic 로케이터 우선: snapshot 없이 바로 조작할 때는 --role, --text, --label, --placeholder 플래그 활용.
• 세션 격리: -s <name> 플래그로 독립적인 브라우저 세션 관리. 기본 세션명은 default.
• 브라우저 바이너리 설치: 처음 사용 시 브라우저 바이너리가 없으면 sw install-browser 실행.