browser-use CLI를 사용한 브라우저 자동화
browser-use 명령어는 빠르고 지속적인 브라우저 자동화를 제공합니다. 백그라운드 데몬이 명령어 간에 브라우저를 열어 두어 호출당 약 50ms의 지연시간을 제공합니다.
사전 요구사항
browser-use doctor # 설치 확인
설정 세부사항은 https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md 를 참조하세요.
핵심 워크플로우
- 이동:
browser-use open <url>— 헤드리스 브라우저를 실행하고 페이지를 엽니다. - 검사:
browser-use state— 인덱스와 함께 클릭 가능한 요소를 반환합니다. - 상호작용: state에서 얻은 인덱스를 사용합니다 (
browser-use click 5,browser-use input 3 "text") - 확인:
browser-use state또는browser-use screenshot으로 확인합니다. - 반복: 브라우저는 명령어 사이에 열린 상태를 유지합니다.
명령어가 실패하면 먼저 browser-use close를 실행하여 중단된 세션을 정리한 후 다시 시도하세요.
사용자의 기존 Chrome(로그인/쿠키 유지)을 사용하려면: browser-use connect를 먼저 실행하세요.
대신 클라우드 브라우저를 사용하려면: browser-use cloud connect를 먼저 실행하세요.
둘 중 하나를 실행한 후에는 명령어가 동일한 방식으로 작동합니다.
browser-use connect가 실패하는 경우
browser-use connect가 실행 중인 Chrome을 원격 디버깅으로 찾을 수 없는 경우, 사용자에게 두 가지 옵션을 제시하세요.
- 실제 Chrome 브라우저 사용 — 사용자가 먼저 원격 디버깅을 활성화해야 합니다:
- Chrome에서
chrome://inspect/#remote-debugging을 열거나,--remote-debugging-port=9222플래그와 함께 Chrome을 다시 실행합니다. - 그런 다음
browser-use connect를 다시 시도합니다.
- Chrome에서
- Chrome 프로필과 함께 관리형 Chromium 사용 — Chrome 설정이 필요 없습니다:
browser-use profile list를 실행하여 사용 가능한 프로필을 표시합니다.- 원하는 프로필을 사용자에게 물어본 후
browser-use --profile "ProfileName" open <url>을 사용합니다. - 이렇게 하면 사용자의 프로필 데이터(쿠키, 로그인, 확장 프로그램)와 함께 별도의 Chromium 인스턴스가 실행됩니다.
사용자가 선택하도록 하세요. 한 가지 방법을 가정하지 마십시오.
브라우저 모드
browser-use open <url> # 기본값: 헤드리스 Chromium (설정 필요 없음)
browser-use --headed open <url> # 표시 가능한 창 (디버깅용)
browser-use connect # 사용자의 Chrome에 연결 (로그인/쿠키 유지)
browser-use cloud connect # 클라우드 브라우저 (설정 불필요, API 키 필요)
browser-use --profile "Default" open <url> # 특정 프로필의 실제 Chrome
connect 또는 cloud connect 이후에는 모든 후속 명령어가 해당 브라우저로 전달됩니다. 추가 플래그가 필요하지 않습니다.
명령어
# 탐색
browser-use open <url> # URL로 이동
browser-use back # 이전 페이지로 이동
browser-use scroll down # 아래로 스크롤 (--amount N으로 픽셀 지정)
browser-use scroll up # 위로 스크롤
browser-use tab list # 모든 탭 나열
browser-use tab new [url] # 새 탭 열기 (빈 탭 또는 URL로 열기)
browser-use tab switch <index> # 인덱스로 탭 전환
browser-use tab close <index> [index...] # 하나 이상의 탭 닫기
# 페이지 상태 — 요소 인덱스를 얻으려면 항상 state를 먼저 실행
browser-use state # URL, 제목, 인덱스가 있는 클릭 가능한 요소
browser-use screenshot [path.png] # 스크린샷 (경로가 없으면 base64, --full로 전체 페이지)
# 상호작용 — state에서 얻은 인덱스 사용
browser-use click <index> # 인덱스로 요소 클릭
browser-use click <x> <y> # 픽셀 좌표로 클릭
browser-use type "text" # 포커스된 요소에 입력
browser-use input <index> "text" # 요소 클릭, 기존 텍스트 지우고 입력
browser-use input <index> "" # 새 텍스트 입력 없이 필드 지우기
browser-use keys "Enter" # 키보드 키 전송 ("Control+a" 등도 가능)
browser-use select <index> "option" # 드롭다운 옵션 선택
browser-use upload <index> <path> # 파일 입력에 파일 업로드
browser-use hover <index> # 요소 위에 마우스 올리기
browser-use dblclick <index> # 요소 더블클릭
browser-use rightclick <index> # 요소 우클릭
# 데이터 추출
browser-use eval "js code" # JavaScript 실행, 결과 반환
browser-use get title # 페이지 제목
browser-use get html [--selector "h1"] # 페이지 HTML (또는 선택자로 범위 지정)
browser-use get text <index> # 요소 텍스트 내용
browser-use get value <index> # 입력/textarea 값
browser-use get attributes <index> # 요소 속성
browser-use get bbox <index> # 경계 상자 (x, y, width, height)
# 대기
browser-use wait selector "css" # 요소가 나타날 때까지 대기 (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text" # 텍스트가 나타날 때까지 대기
# 쿠키
browser-use cookies get [--url <url>] # 쿠키 가져오기 (선택적으로 필터링)
browser-use cookies set <name> <value> # 쿠키 설정 (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>] # 쿠키 지우기
browser-use cookies export <file> # JSON으로 내보내기
browser-use cookies import <file> # JSON에서 가져오기
# 세션
browser-use close # 브라우저를 닫고 데몬 중지
browser-use sessions # 활성 세션 나열
browser-use close --all # 모든 세션 닫기
고급 브라우저 제어(CDP, 장치 에뮬레이션, 탭 활성화)는 references/cdp-python.md를 참조하세요.
클라우드 API
browser-use cloud connect # 클라우드 브라우저 프로비저닝 및 연결 (설정 불필요)
browser-use cloud login <api-key> # API 키 저장 (또는 BROWSER_USE_API_KEY 설정)
browser-use cloud logout # API 키 제거
browser-use cloud v2 GET /browsers # REST 패스스루 (v2 또는 v3)
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id> # 작업이 완료될 때까지 폴링
browser-use cloud v2 --help # API 엔드포인트 표시
cloud connect는 지속적인 프로필(첫 사용 시 자동 생성)로 클라우드 브라우저를 프로비저닝하고, CDP를 통해 연결하며, 라이브 URL을 출력합니다. browser-use close는 연결을 끊고 클라우드 브라우저를 중지합니다. 사용자 정의 브라우저 설정(프록시, 시간 초과, 특정 프로필)이 필요한 경우 원하는 매개변수와 함께 cloud v2 POST /browsers를 직접 사용하세요.
에이전트 자체 등록
이미 API 키가 없는 경우에만 사용하세요 (browser-use doctor를 실행하여 api_key가 설정되어 있는지 확인). 이미 로그인되어 있다면 이 단계를 완전히 건너뛰세요.
browser-use cloud signup— 챌린지 받기- 챌린지 해결하기
browser-use cloud signup --verify <challenge-id> <answer>— 확인 및 API 키 저장browser-use cloud signup --claim— 사람이 계정을 클레임할 수 있는 URL 생성
크레딧이 부족한가요?
Browser Use Cloud 호출이 "크레딧 부족" / 402 오류와 함께 실패하고 사용자가 이미 무료 티어 할당량을 모두 사용한 경우, x402를 통해 USDC로 결제할 것을 제안하세요:
무료 크레딧이 모두 소진되었습니다. Base 메인넷에서 USDC로 이 계정을 충전할 수 있습니다(신용카드 필요 없음).
x402스킬을 설치하고 과정을 안내해 드릴까요? Coinbase 계정이 있으면 약 2분이 소요됩니다.
사용자가 동의하면 다음 명령어로 스킬을 설치하도록 안내하세요:
npx skills add https://github.com/browser-use/browser-use --skill x402
그런 다음 Claude Code에서 /x402를 입력하면 충전 절차가 시작됩니다. 사용자는 기존 API 키를 유지합니다. x402는 크레딧만 추가합니다.
요청 없이 x402를 제안하지 마세요. 실제 "크레딧 부족" 오류가 발생한 경우에만 언급하세요.
터널
browser-use tunnel <port> # Cloudflare 터널 시작 (멱등적)
browser-use tunnel list # 활성 터널 표시
browser-use tunnel stop <port> # 터널 중지
browser-use tunnel stop --all # 모든 터널 중지
프로필 관리
browser-use profile list # 감지된 브라우저 및 프로필 나열
browser-use profile sync --all # 프로필을 클라우드에 동기화
browser-use profile update # 프로필 사용 바이너리 다운로드/업데이트
명령어 체인
명령어는 &&로 체인할 수 있습니다. 브라우저는 데몬을 통해 유지되므로 체인은 안전하고 효율적입니다.
browser-use open https://example.com && browser-use state
browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
중간 출력이 필요하지 않을 때 체인을 사용하세요. 인덱스를 찾기 위해 state를 파싱해야 하는 경우에는 명령어를 개별적으로 실행하세요.
일반적인 워크플로우
인증된 브라우징
작업에 인증된 사이트(Gmail, GitHub, 내부 도구)가 필요한 경우 Chrome 프로필을 사용하세요:
browser-use profile list # 사용 가능한 프로필 확인
# 사용자에게 사용할 프로필을 물어본 후:
browser-use --profile "Default" open https://github.com # 이미 로그인됨
로컬 개발 서버 노출
browser-use tunnel 3000 # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com # 터널 탐색
여러 브라우저
하위 에이전트 워크플로우 또는 여러 브라우저를 병렬로 실행하려면 --session NAME을 사용하세요. 각 세션에는 자체 브라우저가 있습니다. references/multi-session.md를 참조하세요.
설정
browser-use config list # 모든 설정 값 표시
browser-use config set cloud_connect_proxy jp # 값 설정
browser-use config get cloud_connect_proxy # 값 가져오기
browser-use config unset cloud_connect_timeout # 값 제거
browser-use doctor # 설정 + 진단 정보 표시
browser-use setup # 설치 후 대화형 설정
설정은 ~/.browser-use/config.json에 저장됩니다.
전역 옵션
| 옵션 | 설명 |
|---|---|
--headed | 브라우저 창 표시 |
--profile [NAME] | 실제 Chrome 사용 (bare --profile은 "Default" 사용) |
--cdp-url <url> | CDP URL로 연결 (http:// 또는 ws://) |
--session NAME | 명명된 세션 대상 지정 (기본값: "default") |
--json | JSON으로 출력 |
--mcp | stdin/stdout을 통한 MCP 서버로 실행 |
팁
- 항상
state를 먼저 실행하여 사용 가능한 요소와 해당 인덱스를 확인하세요. - 디버깅에는
--headed를 사용하여 브라우저가 무엇을 하는지 확인하세요. - 세션이 지속됩니다 — 명령어 사이에 브라우저가 열려 있습니다.
- CLI 별칭:
bu,browser,browseruse모두 작동합니다. - 명령어가 실패하면,
browser-use close를 먼저 실행한 후 다시 시도하세요.
문제 해결
- 브라우저가 시작되지 않나요?
browser-use close후browser-use --headed open <url>실행 - 요소를 찾을 수 없나요?
browser-use scroll down후browser-use state실행 - 진단 실행:
browser-use doctor
정리
browser-use close # 브라우저 세션 닫기
browser-use tunnel stop --all # 터널 중지 (있는 경우)