cli-anything-browser

¿Qué hace cli-anything-browser?

Interfaz de línea de comandos para automatización de navegador usando el servidor MCP de DOMShell. Navega páginas web usando comandos de sistema de archivos: ls, cd, cat, grep, click.

Instalación

Requisitos previos

1. Node.js y npx (para el servidor MCP de DOMShell):

   # Instalar Node.js desde https://nodejs.org/
   npx --version
   

2. Chrome/Chromium con la extensión DOMShell:

   • Instala la extensión en Chrome
   • Asegúrate de que Chrome esté ejecutándose antes de usar la CLI

3. Python 3.10+

Instalar la CLI

cd browser/agent-harness
pip install -e .

Grupos de comandos

page — Navegación de página

• page open <url> — Navegar a una URL
• page reload — Recargar la página actual
• page back — Retroceder en el historial
• page forward — Avanzar en el historial
• page info — Mostrar información de la página actual

fs — Comandos del sistema de archivos (Árbol de Accesibilidad)

• fs ls [ruta] — Listar elementos en la ruta
• fs cd <ruta> — Cambiar de directorio
• fs cat [ruta] — Leer contenido del elemento
• fs grep <patrón> [ruta] — Buscar un patrón de texto
• fs pwd — Imprimir el directorio de trabajo

act — Comandos de acción

• act click <ruta> — Hacer clic en un elemento
• act type <ruta> <texto> — Escribir texto en un campo de entrada

session — Gestión de sesiones

• session status — Mostrar estado de la sesión
• session daemon-start — Iniciar modo daemon persistente
• session daemon-stop — Detener modo daemon

Ejemplos de uso

Navegación básica

# Abrir una página
cli-anything-browser page open https://example.com

# Explorar estructura
cli-anything-browser fs ls /
cli-anything-browser fs cd /main
cli-anything-browser fs ls

# Volver a la raíz
cli-anything-browser fs cd /

Búsqueda y clic

cli-anything-browser fs grep "Iniciar sesión"
cli-anything-browser act click /main/button[0]

Rellenar formulario

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

Salida JSON

cli-anything-browser --json fs ls /

Modo Daemon (uso interactivo más rápido)

# Iniciar conexión persistente
cli-anything-browser session daemon-start

# Ejecutar comandos (usa la conexión persistente)
cli-anything-browser fs ls /
cli-anything-browser fs cd /main

# Detener daemon al terminar
cli-anything-browser session daemon-stop

REPL interactivo

cli-anything-browser

Sintaxis de rutas

DOMShell usa una ruta similar a sistema de archivos para el Árbol de Accesibilidad:

/                           — Raíz (documento)
/main                       — Hito principal
/main/div[0]                — Primer div en main
/main/div[0]/button[2]      — Tercer botón en el primer div

• Los índices de arreglo son base 0: button[0] es el primer botón
• Usa .. para subir un nivel
• Usa / para la raíz

Orientación específica para agentes

Salida JSON para análisis

Todos los comandos admiten la bandera --json para obtener una salida legible por máquina:

cli-anything-browser --json fs ls /

Devuelve:

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

Manejo de errores

La CLI proporciona mensajes de error claros para problemas comunes:

• npx no encontrado: Instalar Node.js desde https://nodejs.org/
• DOMShell no encontrado: Ejecutar npx @apireno/domshell --version
• Llamada MCP fallida: Instalar la extensión DOMShell de Chrome

Verifica el valor de retorno de is_available() antes de ejecutar comandos.

Modo Daemon para eficiencia

Para flujos de trabajo de agente con múltiples comandos, usa el modo daemon:

1. Iniciar daemon: cli-anything-browser session daemon-start
2. Ejecutar comandos: Cada comando reutiliza la conexión MCP
3. Detener daemon: cli-anything-browser session daemon-stop

Esto evita la sobrecarga de 1-3 segundos de arranque en frío para cada comando.

Enlaces

• DOMShell GitHub
• CLI-Anything
• Issue #90

Consideraciones de seguridad

IMPORTANTE: Al usar esta CLI con agentes de IA, ten en cuenta las siguientes consideraciones de seguridad:

Restricciones de URL

El arnés del navegador valida todas las URLs antes de la navegación:

• Esquema explícito requerido: Las URLs deben incluir el esquema http:// o https:// (las URLs sin esquema como ejemplo.com son rechazadas)
• Esquemas bloqueados: file://, javascript://, data://, vbscript://, about://, chrome:// y esquemas internos del navegador
• Esquemas permitidos: Solo http:// y https:// (configurable mediante CLI_ANYTHING_BROWSER_ALLOWED_SCHEMES)
• Bloqueo de red privada: Opcional mediante CLI_ANYTHING_BROWSER_BLOCK_PRIVATE=true (deshabilitado por defecto)

Riesgos del contenido DOM

El Árbol de Accesibilidad incluye todos los elementos visibles y ocultos de una página. Los sitios web maliciosos podrían:

• Crear etiquetas ARIA con texto manipulador (por ejemplo, "Ignorar instrucciones anteriores")
• Usar elementos ocultos por aria-hidden para inyectar contenido no visible para los usuarios
• Crear estructuras DOM confusas que engañen la navegación

Mitigación: Al interactuar con sitios web no confiables, considera:

1. Usar la bandera --json para obtener una salida estructurada más fácil de analizar de forma segura
2. Sanear o filtrar el contenido DOM antes de incluirlo en prompts
3. Limitar la navegación a dominios confiables

Acceso a red privada

Por defecto, el navegador puede acceder a localhost y redes privadas (192.168.x.x, 10.x.x.x, etc.). Para bloquearlo:

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

Aislamiento de sesiones

Varias sesiones del navegador comparten la misma instancia de Chrome. Las cookies y el estado de autenticación pueden persistir entre sesiones. Para operaciones sensibles, considera:

1. Usar el modo invitado o incógnito de Chrome
2. Limpiar las cookies entre sesiones
3. Usar perfiles de Chrome separados para diferentes contextos de seguridad