agent-browser

명령어

기본

agent-browser open <url>              # 이동 (별칭: goto, navigate)
agent-browser click <sel>             # 요소 클릭 (--new-tab로 새 탭에서 열기)
agent-browser dblclick <sel>          # 두 번 클릭
agent-browser fill <sel> <text>       # 지우고 입력
agent-browser type <sel> <text>       # 요소에 텍스트 입력
agent-browser press <key>             # 키 누름 (Enter, Tab, Control+a) (별칭: key)
agent-browser keyboard type <text>    # 현재 포커스 위치에 텍스트 입력 (선택자 필요 없음)
agent-browser keyboard inserttext <text>  # 키 이벤트 없이 텍스트 삽입
agent-browser keydown <key>           # 키를 누른 상태로 유지
agent-browser keyup <key>             # 키 해제
agent-browser hover <sel>             # 요소 위로 마우스를 올림
agent-browser focus <sel>             # 요소에 포커스
agent-browser select <sel> <val>      # 드롭다운 옵션 선택
agent-browser check <sel>             # 체크박스 체크
agent-browser uncheck <sel>           # 체크박스 체크 해제
agent-browser scroll <dir> [px]       # 스크롤 (위/아래/왼쪽/오른쪽, --selector <sel>)
agent-browser scrollintoview <sel>    # 요소가 보이도록 스크롤
agent-browser drag <src> <dst>        # 드래그 앤 드롭
agent-browser upload <sel> <files>    # 파일 업로드
agent-browser screenshot [path]       # 스크린샷 (--full로 전체 페이지 캡처)
agent-browser screenshot --annotate   # 번호 매긴 요소 레이블이 있는 설명 포함 스크린샷
agent-browser pdf <path>              # 페이지를 PDF로 저장
agent-browser snapshot                # 참조 정보 포함 접근성 트리
agent-browser eval <js>               # 자바스크립트 실행
agent-browser connect <port|url>      # CDP를 통해 브라우저 연결
agent-browser close                   # 브라우저 닫기 (별칭: quit, exit)

정보 얻기

agent-browser get text <sel>          # 텍스트 내용 가져오기
agent-browser get html <sel>          # innerHTML 가져오기
agent-browser get value <sel>         # 입력 값 가져오기
agent-browser get attr <sel> <attr>   # 속성 가져오기
agent-browser get title               # 페이지 제목 가져오기
agent-browser get url                 # 현재 URL 가져오기
agent-browser get count <sel>         # 일치하는 요소 수 계산
agent-browser get box <sel>           # 경계 상자 가져오기
agent-browser get styles <sel>        # 계산된 스타일 가져오기

상태 확인

agent-browser is visible <sel>        # 표시 여부 확인
agent-browser is enabled <sel>        # 활성화 여부 확인
agent-browser is checked <sel>        # 체크 여부 확인

요소 찾기

작업이 포함된 의미적 선택자 (click, fill, type, hover, focus, check, uncheck, text):

agent-browser find role <role> <action> [value]
agent-browser find text <text> <action>
agent-browser find label <label> <action> [value]
agent-browser find placeholder <ph> <action> [value]
agent-browser find alt <text> <action>
agent-browser find title <text> <action>
agent-browser find testid <id> <action> [value]
agent-browser find first <sel> <action> [value]
agent-browser find last <sel> <action> [value]
agent-browser find nth <n> <sel> <action> [value]

옵션:

  • --name <name> -- 접근 가능한 이름으로 역할 필터링
  • --exact -- 정확한 텍스트 일치 요구

예시:

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "[email protected]"
agent-browser find alt "Logo" click
agent-browser find first ".item" click
agent-browser find last ".item" text
agent-browser find nth 2 ".card" hover

대기

agent-browser wait <selector>         # 요소 대기
agent-browser wait <ms>               # 시간 대기
agent-browser wait --text "Welcome"   # 텍스트 대기
agent-browser wait --url "**/dash"    # URL 패턴 대기
agent-browser wait --load networkidle # 로드 상태 대기
agent-browser wait --fn "condition"   # JS 조건 대기
agent-browser wait --download [path]  # 다운로드 완료 대기

다운로드

agent-browser download <sel> <path>   # 요소 클릭하여 다운로드 시작
agent-browser wait --download [path]  # 모든 다운로드 완료 대기

기본 다운로드 디렉토리를 설정하려면 --download-path <dir>(또는 AGENT_BROWSER_DOWNLOAD_PATH 환경 변수)를 사용하세요. 그렇지 않으면 브라우저 종료 시 삭제되는 임시 디렉토리로 다운로드됩니다.

마우스

agent-browser mouse move <x> <y>      # 마우스 이동
agent-browser mouse down [button]     # 버튼 누름
agent-browser mouse up [button]       # 버튼 뗌
agent-browser mouse wheel <dy> [dx]   # 휠 스크롤

설정

agent-browser set viewport <w> <h>    # 뷰포트 크기 설정
agent-browser set device <name>       # 기기 에뮬레이션 ("iPhone 14")
agent-browser set geo <lat> <lng>     # 위치 정보 설정
agent-browser set offline [on|off]    # 오프라인 모드 전환
agent-browser set headers <json>      # 추가 HTTP 헤더
agent-browser set credentials <u> <p> # HTTP 기본 인증
agent-browser set media [dark|light]  # 색상 테마 에뮬레이션 (세션 동안 유지)

지속적인 다크/라이트 모드를 모든 명령어에 적용하려면 --color-scheme를 사용하세요:

agent-browser --color-scheme dark open https://example.com

쿠키 및 저장소

agent-browser cookies                 # 모든 쿠키 가져오기
agent-browser cookies set <name> <val> # 쿠키 설정
agent-browser cookies clear           # 쿠키 삭제

agent-browser storage local           # 모든 localStorage 가져오기
agent-browser storage local <key>     # 특정 키 가져오기
agent-browser storage local set <k> <v>  # 값 설정
agent-browser storage local clear     # 모두 삭제

agent-browser storage session         # sessionStorage에 동일한 명령어 사용

네트워크

agent-browser network route <url>              # 요청 가로채기
agent-browser network route <url> --abort      # 요청 차단
agent-browser network route <url> --body <json>  # 응답 가짜 만들기
agent-browser network unroute [url]            # 루트 제거
agent-browser network requests                 # 추적된 요청 보기
agent-browser network requests --clear         # 요청 로그 지우기
agent-browser network requests --filter <pat>  # URL 패턴으로 필터링

탭 및 프레임

agent-browser tab                     # 탭 목록 보기
agent-browser tab new [url]           # 새 탭 열기
agent-browser tab <n>                 # 탭 전환
agent-browser tab close [n]           # 탭 닫기
agent-browser window new              # 새 브라우저 창 열기
agent-browser frame <sel>             # iframe 전환
agent-browser frame main              # 메인 프레임으로 돌아가기

대화상자

agent-browser dialog accept [text]    # 대화상자 수락 (옵션 프롬프트 텍스트 포함)
agent-browser dialog dismiss          # 대화상자 취소

디버그

agent-browser trace start [path]      # 트레이스 시작
agent-browser trace stop [path]       # 트레이스 중지 및 저장
agent-browser profiler start          # Chrome DevTools 프로파일링 시작
agent-browser profiler stop [path]    # 프로파일링 중지 및 저장 (.json 파일)
agent-browser record start <path>     # 비디오 녹화 시작 (WebM 형식)
agent-browser record stop             # 녹화 중지 및 저장
agent-browser record restart <path>   # 현재 녹화 중지 후 새로운 녹화 시작
agent-browser console                 # 콘솔 메시지 보기
agent-browser console --clear         # 콘솔 로그 지우기
agent-browser errors                  # 페이지 오류 보기
agent-browser errors --clear          # 오류 로그 지우기
agent-browser highlight <sel>         # 요소 강조

인증 보관소

agent-browser auth save <name> [opts]    # 인증 프로필 저장
agent-browser auth login <name>          # 저장된 자격 증명으로 로그인
agent-browser auth list                  # 저장된 프로필 목록 (이름과 URL만)
agent-browser auth show <name>           # 프로필 메타데이터 보기 (비밀번호 제외)
agent-browser auth delete <name>         # 저장된 프로필 삭제

저장 옵션:

  • --url <url> -- 로그인 페이지 주소 (필수)
  • --username <user> -- 사용자 이름 (필수)
  • --password <pass> -- 비밀번호 (필수, --password-stdin 제외 시)
  • --password-stdin -- 비밀번호를 표준 입력에서 읽기 (쉘 히스토리 노출 방지를 위해 권장)
  • --username-selector <sel> -- 사용자 이름 필드용 사용자 정의 CSS 선택자
  • --password-selector <sel> -- 비밀번호 필드용 사용자 정의 CSS 선택자
  • --submit-selector <sel> -- 제출 버튼용 사용자 정의 CSS 선택자
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github
agent-browser auth list

확인

--confirm-actions가 설정되면 일부 작업 카테고리는 즉시 실행되지 않고 confirmation_required 응답을 반환합니다. confirm 또는 deny 명령어로 작업을 승인하거나 거부하세요.

agent-browser confirm <confirmation-id>  # 보류 중인 작업 승인
agent-browser deny <confirmation-id>     # 보류 중인 작업 거부

보류 중인 확인은 60초 후 자동으로 거부됩니다.

agent-browser --confirm-actions eval,download eval "document.title"
# ID를 포함한 confirmation_required 반환
agent-browser confirm c_8f3a1234

상태 관리

agent-browser state save <path>       # 인증 상태를 파일에 저장
agent-browser state load <path>       # 파일에서 인증 상태 불러오기
agent-browser state list              # 저장된 상태 파일 목록 보기
agent-browser state show <file>       # 상태 요약 보기
agent-browser state rename <old> <new> # 상태 파일 이름 바꾸기
agent-browser state clear [name]      # 세션 이름에 해당하는 상태 삭제
agent-browser state clear --all       # 모든 저장된 상태 삭제
agent-browser state clean --older-than <days>  # 오래된 상태 삭제

세션

agent-browser session                 # 현재 세션 이름 표시
agent-browser session list            # 활성 세션 목록 보기

탐색

agent-browser back                    # 이전 페이지로 이동
agent-browser forward                 # 다음 페이지로 이동
agent-browser reload                  # 페이지 새로 고침

전역 옵션

--session <name>         # 격리된 브라우저 세션
--session-name <name>    # 자동 저장/복원 세션 상태 (쿠키, localStorage)
--profile <path>         # 지속적인 브라우저 프로필 디렉토리
--state <path>           # JSON 파일에서 저장소 상태 로드
--headers <json>         # URL의 원본 범위 내에서 스코프된 HTTP 헤더
--executable-path <path> # 사용자 정의 브라우저 실행 파일
--extension <path>       # 브라우저 확장 로드 (반복 가능)
--args <args>            # 브라우저 시작 인수 (쉼표 구분)
--user-agent <ua>        # 사용자 정의 User-Agent 문자열
--proxy <url>            # 프록시 서버 주소
--proxy-bypass <hosts>   # 프록시를 우회할 호스트
--ignore-https-errors    # HTTPS 인증서 오류 무시
--allow-file-access      # file:// URL이 로컬 파일에 접근 허용 (크롬만 해당)
-p, --provider <name>    # 브라우저 제공자 (ios, browserbase, kernel, browseruse)
--device <name>          # iOS 기기 이름 (예: "iPhone 15 Pro")
--json                   # JSON 출력 (스크립트용)
--full, -f               # 전체 페이지 스크린샷
--annotate               # 번호 매긴 요소 레이블이 있는 설명 포함 스크린샷
--headed                 # 브라우저 창 표시 (헤드리스 아님)
--cdp <port|url>         # Chrome DevTools Protocol을 통한 연결 (포트 또는 웹소켓 주소)
--auto-connect           # 실행 중인 크롬을 자동 검색하고 연결
--color-scheme <scheme>  # 색상 테마: dark, light, no-preference
--download-path <path>   # 기본 다운로드 디렉토리
--content-boundaries     # LLM 안전성을 위해 페이지 출력을 경계 마커로 감싸기
--max-output <chars>     # 페이지 출력을 최대 N자로 자르기
--allowed-domains <list> # 쉼표로 구분된 허용 도메인 패턴 목록
--action-policy <path>   # 액션 정책 JSON 파일 경로
--confirm-actions <list> # 확인이 필요한 액션 카테고리
--confirm-interactive    # 인터랙티브 확인 프롬프트 (입력이 터미널이 아닌 경우 자동 거부)
--config <path>          # 사용자 정의 구성 파일 사용
--debug                  # 디버그 출력

명령 체이닝

단일 쉘 호출 내에서 &&를 사용하여 명령어를 체인하세요. 브라우저는 백그라운드 데몬을 통해 유지되므로, 체인이 자연스럽게 작동하며 별도 호출보다 효율적입니다:

agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "pass" && agent-browser click @e3
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

중간 출력을 읽을 필요가 없다면 &&를 사용하세요. 출력을 먼저 분석해야 하는 경우(예: 스냅샷을 통해 참조 식별 후 해당 참조로 상호작용)는 명령어를 별도로 실행하세요.

로컬 파일

file:// URL을 사용하여 로컬 파일(PDF, HTML)을 열 수 있습니다:

agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

--allow-file-access 플래그는 자바스크립트가 다른 로컬 파일에 접근하도록 허용합니다. 크롬 전용.