cli-anything-browser

O que cli-anything-browser faz?

Uma interface de linha de comando para automação de navegador usando o servidor MCP do DOMShell. Navegue por páginas web usando comandos de sistema de arquivos: ls, cd, cat, grep, click.

Instalação

Pré-requisitos

1. Node.js e npx (para o servidor MCP DOMShell):

   # Instale o Node.js de https://nodejs.org/
   npx --version
   

2. Chrome/Chromium com a extensão DOMShell:

   • Instale a extensão no Chrome
   • Certifique-se de que o Chrome está em execução antes de usar o CLI

3. Python 3.10+

Instalar o CLI

cd browser/agent-harness
pip install -e .

Grupos de Comandos

page — Navegação de Página

• page open <url> — Navegar para uma URL
• page reload — Recarregar a página atual
• page back — Voltar no histórico
• page forward — Avançar no histórico
• page info — Mostrar informações da página atual

fs — Comandos de Sistema de Arquivos (Árvore de Acessibilidade)

• fs ls [caminho] — Listar elementos em um caminho
• fs cd <caminho> — Mudar de diretório
• fs cat [caminho] — Ler o conteúdo de um elemento
• fs grep <padrão> [caminho] — Pesquisar por um padrão de texto
• fs pwd — Imprimir o diretório de trabalho

act — Comandos de Ação

• act click <caminho> — Clicar em um elemento
• act type <caminho> <texto> — Digitar texto em um campo de entrada

session — Gerenciamento de Sessão

• session status — Mostrar o estado da sessão
• session daemon-start — Iniciar o modo daemon persistente
• session daemon-stop — Parar o modo daemon

Exemplos de Uso

Navegação Básica

# Abrir uma página
cli-anything-browser page open https://exemplo.com.br

# Explorar a estrutura
cli-anything-browser fs ls /
cli-anything-browser fs cd /main
cli-anything-browser fs ls

# Voltar para a raiz
cli-anything-browser fs cd /

Pesquisa e Clique

cli-anything-browser fs grep "Login"
cli-anything-browser act click /main/button[0]

Preenchimento de Formulário

cli-anything-browser act type /main/input[0] "[email protected]"
cli-anything-browser act click /main/button[0]

Saída JSON

cli-anything-browser --json fs ls /

Modo Daemon (Uso Interativo Mais Rápido)

# Iniciar conexão persistente
cli-anything-browser session daemon-start

# Executar comandos (usa a conexão persistente)
cli-anything-browser fs ls /
cli-anything-browser fs cd /main

# Parar o daemon quando terminar
cli-anything-browser session daemon-stop

REPL Interativo

cli-anything-browser

Sintaxe de Caminhos

O DOMShell usa um caminho semelhante a sistema de arquivos para a Árvore de Acessibilidade:

/                           — Raiz (documento)
/main                       — Landmark principal
/main/div[0]                — Primeira div no main
/main/div[0]/button[2]      — Terceiro botão na primeira div

• Índices de array são baseados em 0: button[0] é o primeiro botão
• Use .. para subir um nível
• Use / para a raiz

Orientações Específicas para Agentes

Saída JSON para Análise

Todos os comandos suportam a flag --json para saída legível por máquina:

cli-anything-browser --json fs ls /

Retorna:

{
  "path": "/",
  "entries": [
    {"name": "main", "role": "landmark", "path": "/main"}
  ]
}

Tratamento de Erros

O CLI fornece mensagens de erro claras para problemas comuns:

• npx não encontrado: Instale o Node.js de https://nodejs.org/
• DOMShell não encontrado: Execute npx @apireno/domshell --version
• Falha na chamada MCP: Instale a extensão DOMShell do Chrome

Verifique o valor de retorno de is_available() antes de executar comandos.

Modo Daemon para Eficiência

Para fluxos de trabalho de agente com múltiplos comandos, use o modo daemon:

1. Inicie o daemon: cli-anything-browser session daemon-start
2. Execute comandos: Cada comando reutiliza a conexão MCP
3. Pare o daemon: cli-anything-browser session daemon-stop

Isso evita a sobrecarga de inicialização a frio de 1 a 3 segundos para cada comando.

Links

• DOMShell GitHub
• CLI-Anything
• Issue #90

Considerações de Segurança

IMPORTANTE: Ao usar este CLI com agentes de IA, esteja ciente das seguintes considerações de segurança:

Restrições de URL

O harness do navegador valida todas as URLs antes da navegação:

• Esquema explícito obrigatório: As URLs devem incluir o esquema http:// ou https:// (URLs sem esquema, como exemplo.com.br, são rejeitadas)
• Esquemas bloqueados: file://, javascript://, data://, vbscript://, about://, chrome:// e esquemas internos do navegador
• Esquemas permitidos: Apenas http:// e https:// (configurável via CLI_ANYTHING_BROWSER_ALLOWED_SCHEMES)
• Bloqueio de rede privada: Opcional via CLI_ANYTHING_BROWSER_BLOCK_PRIVATE=true (desativado por padrão)

Riscos de Conteúdo DOM

A Árvore de Acessibilidade inclui todos os elementos visíveis e ocultos de uma página. Sites maliciosos podem:

• Criar rótulos ARIA com texto manipulador (por exemplo, "Ignore as instruções anteriores")
• Usar elementos aria-hidden para injetar conteúdo não visível aos usuários
• Criar estruturas DOM confusas que enganam a navegação

Mitigação: Ao interagir com sites não confiáveis, considere:

1. Usar a flag --json para saída estruturada que é mais fácil de analisar com segurança
2. Sanitizar ou filtrar o conteúdo DOM antes de incluí-lo em prompts
3. Limitar a navegação a domínios confiáveis

Acesso à Rede Privada

Por padrão, o navegador pode acessar localhost e redes privadas (192.168.x.x, 10.x.x.x, etc.). Para bloquear:

export CLI_ANYTHING_BROWSER_BLOCK_PRIVATE=true
cli-anything-browser page open http://localhost:8080  # Será bloqueado

Isolamento de Sessão

Múltiplas sessões do navegador compartilham a mesma instância do Chrome. Cookies e estado de autenticação podem persistir entre sessões. Para operações sensíveis, considere:

1. Usar o modo convidado ou anônimo do Chrome
2. Limpar cookies entre sessões
3. Usar perfis separados do Chrome para diferentes contextos de segurança