browser-use

Automação de Navegador com browser-use CLI

O comando browser-use fornece automação de navegador rápida e persistente. Um daemon em segundo plano mantém o navegador aberto entre os comandos, resultando em latência de aproximadamente 50ms por chamada.

Pré-requisitos

browser-use doctor    # Verificar instalação

Para detalhes de configuração, veja https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Fluxo de Trabalho Principal

1. Navegar: browser-use open <url> — inicia navegador headless e abre a página
2. Inspecionar: browser-use state — retorna elementos clicáveis com índices
3. Interagir: use índices do state (browser-use click 5, browser-use input 3 "texto")
4. Verificar: browser-use state ou browser-use screenshot para confirmar
5. Repetir: navegador permanece aberto entre comandos

Se um comando falhar, execute browser-use close primeiro para limpar qualquer sessão quebrada e tente novamente.

Para usar o Chrome existente do usuário (preserva logins/cookies): execute browser-use connect primeiro. Para usar um navegador em nuvem: execute browser-use cloud connect primeiro. Após qualquer um dos dois, os comandos funcionam da mesma forma.

Se browser-use connect falhar

Quando browser-use connect não consegue encontrar um Chrome em execução com depuração remota, pergunte ao usuário duas opções:

1. Usar o navegador Chrome real — eles precisam ativar a depuração remota primeiro:
   • Abra chrome://inspect/#remote-debugging no Chrome, ou reinicie o Chrome com --remote-debugging-port=9222
   • Depois tente novamente browser-use connect
2. Usar Chromium gerenciado com o perfil Chrome — sem necessidade de configurar Chrome:
   • Execute browser-use profile list para mostrar os perfis disponíveis
   • Pergunte qual perfil o usuário deseja usar, depois use browser-use --profile "NomeDoPerfil" open <url>
   • Isso inicia uma instância separada do Chromium com os dados do perfil (cookies, logins, extensões)

Deixe o usuário escolher — não assuma um caminho sobre o outro.

Modos de Navegador

browser-use open <url>                         # Padrão: Chromium headless (sem configuração)
browser-use --headed open <url>                # Janela visível (para depuração)
browser-use connect                            # Conectar ao Chrome do usuário (preserva logins/cookies)
browser-use cloud connect                      # Navegador em nuvem (zero-config, requer chave de API)
browser-use --profile "Default" open <url>     # Chrome real com perfil específico

Após connect ou cloud connect, todos os comandos subsequentes vão para esse navegador — sem necessidade de flags extras.

Comandos

# Navegação
browser-use open <url>                    # Navegar para URL
browser-use back                          # Voltar no histórico
browser-use scroll down                   # Rolar para baixo (--amount N para pixels)
browser-use scroll up                     # Rolar para cima
browser-use tab list                      # Listar todas as abas
browser-use tab new [url]                 # Abrir nova aba (em branco ou com URL)
browser-use tab switch <index>            # Alternar para aba por índice
browser-use tab close <index> [index...]  # Fechar uma ou mais abas

# Estado da Página — sempre execute state primeiro para obter índices dos elementos
browser-use state                         # URL, título, elementos clicáveis com índices
browser-use screenshot [caminho.png]      # Screenshot (base64 se sem caminho, --full para página completa)

# Interações — use índices do state
browser-use click <index>                 # Clicar no elemento pelo índice
browser-use click <x> <y>                 # Clicar nas coordenadas do pixel
browser-use type "texto"                  # Digitar no elemento focado
browser-use input <index> "texto"         # Clicar no elemento, limpar texto existente, depois digitar
browser-use input <index> ""              # Limpar um campo sem digitar novo texto
browser-use keys "Enter"                  # Enviar teclas do teclado (também "Control+a", etc.)
browser-use select <index> "opção"        # Selecionar opção de dropdown
browser-use upload <index> <caminho>      # Enviar arquivo para input de arquivo
browser-use hover <index>                 # Passar o mouse sobre o elemento
browser-use dblclick <index>              # Clique duplo no elemento
browser-use rightclick <index>            # Clique direito no elemento

# Extração de Dados
browser-use eval "código js"               # Executar JavaScript, retornar resultado
browser-use get title                     # Título da página
browser-use get html [--selector "h1"]    # HTML da página (ou escopo para o seletor)
browser-use get text <index>              # Conteúdo de texto do elemento
browser-use get value <index>             # Valor do input/textarea
browser-use get attributes <index>        # Atributos do elemento
browser-use get bbox <index>              # Bounding box (x, y, largura, altura)

# Aguardar
browser-use wait selector "css"           # Aguardar por elemento (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "texto"            # Aguardar o texto aparecer

# Cookies
browser-use cookies get [--url <url>]     # Obter cookies (opcionalmente filtrados)
browser-use cookies set <nome> <valor>    # Definir cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Limpar cookies
browser-use cookies export <arquivo>      # Exportar para JSON
browser-use cookies import <arquivo>      # Importar de JSON

# Sessão
browser-use close                         # Fechar navegador e parar daemon
browser-use sessions                      # Listar sessões ativas
browser-use close --all                   # Fechar todas as sessões

Para controle avançado do navegador (CDP, emulação de dispositivo, ativação de aba), veja references/cdp-python.md.

API de Nuvem

browser-use cloud connect                 # Provisionar navegador em nuvem e conectar (zero-config)
browser-use cloud login <chave-api>       # Salvar chave de API (ou definir BROWSER_USE_API_KEY)
browser-use cloud logout                  # Remover chave de API
browser-use cloud v2 GET /browsers        # Passagem REST (v2 ou v3)
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <id-tarefa>     # Poll da tarefa até concluir
browser-use cloud v2 --help               # Mostrar endpoints da API

cloud connect provisiona um navegador em nuvem com perfil persistente (criado automaticamente no primeiro uso), conecta via CDP e imprime uma URL ativa. browser-use close desconecta E para o navegador em nuvem. Para configurações personalizadas do navegador (proxy, timeout, perfil específico), use cloud v2 POST /browsers diretamente com os parâmetros desejados.

Auto-Registro do Agente

Use isso apenas se você já não tiver uma chave de API (verifique com browser-use doctor se api_key está definido). Se já estiver logado, pule completamente este passo.

1. browser-use cloud signup — obter um desafio
2. Resolva o desafio
3. browser-use cloud signup --verify <id-desafio> <resposta> — verificar e salvar chave de API
4. browser-use cloud signup --claim — gerar URL para um humano reivindicar a conta

Sem créditos?

Se uma chamada do Browser Use Cloud falhar com erro "insufficient credits" / 402 e o usuário já tiver usado sua cota gratuita, sugira pagar com USDC via x402:

Seus créditos gratuitos acabaram. Você pode recarregar esta conta com USDC na Base mainnet (sem necessidade de cartão de crédito). Quer que eu instale a skill x402 e te guie por ela? Leva cerca de 2 minutos se você tiver uma conta Coinbase.

Se eles disserem sim, aponte para instalar a skill:

npx skills add https://github.com/browser-use/browser-use --skill x402

Depois /x402 no Claude Code aciona o fluxo de recarga. O usuário mantém sua chave de API existente — x402 apenas adiciona créditos a ela.

Não sugira x402 sem ser solicitado. Mencione apenas em um erro real de "insufficient credits".

Túneis

browser-use tunnel <porta>                 # Iniciar túnel Cloudflare (idempotente)
browser-use tunnel list                   # Mostrar túneis ativos
browser-use tunnel stop <porta>            # Parar túnel
browser-use tunnel stop --all              # Parar todos os túneis

Gerenciamento de Perfis

browser-use profile list                  # Listar navegadores e perfis detectados
browser-use profile sync --all            # Sincronizar perfis com a nuvem
browser-use profile update                # Baixar/atualizar binário profile-use

Encadeamento de Comandos

Comandos podem ser encadeados com &&. O navegador persiste via daemon, então o encadeamento é seguro e eficiente.

browser-use open https://exemplo.com && browser-use state
browser-use input 5 "[email protected]" && browser-use input 6 "senha" && browser-use click 7

Encadeie quando você não precisar de saída intermediária. Execute separadamente quando precisar analisar o state para descobrir índices primeiro.

Fluxos de Trabalho Comuns

Navegação Autenticada

Quando uma tarefa requer um site autenticado (Gmail, GitHub, ferramentas internas), use perfis do Chrome:

browser-use profile list                           # Verificar perfis disponíveis
# Pergunte ao usuário qual perfil usar, depois:
browser-use --profile "Default" open https://github.com  # Já logado

Expondo Servidores de Desenvolvimento Locais

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Navegar no túnel

Múltiplos Navegadores

Para fluxos de trabalho com subagentes ou executando vários navegadores em paralelo, use --session NOME. Cada sessão tem seu próprio navegador. Veja references/multi-session.md.

Configuração

browser-use config list                            # Mostrar todos os valores de configuração
browser-use config set cloud_connect_proxy jp      # Definir um valor
browser-use config get cloud_connect_proxy         # Obter um valor
browser-use config unset cloud_connect_timeout     # Remover um valor
browser-use doctor                                 # Mostrar configuração + diagnósticos
browser-use setup                                  # Configuração interativa pós-instalação

Configuração armazenada em ~/.browser-use/config.json.

Opções Globais

Opção	Descrição
--headed	Mostrar janela do navegador
--profile [NOME]	Usar Chrome real (apenas --profile usa "Default")
--cdp-url <url>	Conectar via URL CDP (http:// ou ws://)
--session NOME	Direcionar uma sessão nomeada (padrão: "default")
--json	Saída como JSON
--mcp	Executar como servidor MCP via stdin/stdout

Dicas

1. Sempre execute state primeiro para ver os elementos disponíveis e seus índices
2. Use --headed para depuração para ver o que o navegador está fazendo
3. Sessões persistem — navegador permanece aberto entre comandos
4. Alias da CLI: bu, browser e browseruse também funcionam
5. Se os comandos falharem, execute browser-use close primeiro, depois tente novamente

Solução de Problemas

• Navegador não inicia? browser-use close depois browser-use --headed open <url>
• Elemento não encontrado? browser-use scroll down depois browser-use state
• Executar diagnósticos: browser-use doctor

Limpeza

browser-use close                         # Fechar sessão do navegador
browser-use tunnel stop --all             # Parar túneis (se houver)