Automatisation de navigateur

Automatisez les interactions de navigateur en utilisant la CLI browse avec Claude.

Vérification de la configuration

Avant d'exécuter des commandes de navigateur, vérifiez que la CLI est disponible :

which browse || npm install -g @browserbasehq/browse-cli

Sélection de l'environnement (Local vs Remote)

La CLI supporte les remplacements explicites par session. Si vous ne faites rien, la session suivante bascule par défaut à Browserbase quand BROWSERBASE_API_KEY est définie, sinon à local.

Mode local

browse env local démarre un navigateur local isolé et propre
browse env local --auto-connect réutilise un Chrome débogable déjà en cours d'exécution et bascule à l'isolé s'il n'y a rien de disponible
browse env local <port|url> se connecte à une cible CDP spécifique
Idéal pour : le développement, localhost, les sites de confiance et les exécutions reproductibles

Mode remote (Browserbase)

browse env remote bascule la session actuelle à Browserbase
Sans remplacément local, Browserbase est aussi le défaut quand BROWSERBASE_API_KEY est définie
Fournit : anti-bot furtif, résolution automatique de CAPTCHA, proxies résidentiels, persistance de session
Utilisez le mode remote quand : le site cible a une détection de bot, des CAPTCHA, des limites de débit IP, la protection Cloudflare ou nécessite un accès géo-spécifique
Obtenez les identifiants à https://browserbase.com/settings

Quand choisir lequel

Tests locaux reproductibles / état propre : browse env local
Réutiliser votre login/cookies local : browse env local --auto-connect
Navigation simple (docs, wikis, APIs publiques) : le mode local convient
Sites protégés (murs de connexion, CAPTCHA, anti-scraping) : utilisez le mode remote
Si le mode local échoue avec détection de bot ou accès refusé : basculez au mode remote

Commandes

Toutes les commandes fonctionnent de manière identique dans les deux modes. Le daemon démarre automatiquement à la première commande.

Navigation

browse open <url>                        # Aller à l'URL (alias : goto)
browse open <url> --context-id <id>      # Charger un contexte Browserbase (remote uniquement)
browse open <url> --context-id <id> --persist  # Charger contexte + enregistrer les modifications
browse reload                            # Recharger la page actuelle
browse back                              # Revenir en arrière dans l'historique
browse forward                           # Avancer dans l'historique

État de la page (privilégier snapshot plutôt que screenshot)

browse snapshot                          # Obtenir l'arbre d'accessibilité avec références d'éléments (rapide, structuré)
browse screenshot [path]                 # Prendre une capture d'écran visuelle (lent, utilise les tokens vision)
browse get url                           # Obtenir l'URL actuelle
browse get title                         # Obtenir le titre de la page
browse get text <selector>               # Obtenir le contenu texte (utiliser "body" pour tout le texte)
browse get html <selector>               # Obtenir le contenu HTML de l'élément
browse get value <selector>              # Obtenir la valeur du champ de formulaire

Utilisez browse snapshot par défaut pour comprendre l'état de la page — il retourne l'arbre d'accessibilité avec les références d'éléments que vous pouvez utiliser pour interagir. N'utilisez browse screenshot que quand vous avez besoin du contexte visuel (disposition, images, débogage).

Interaction

browse click <ref>                       # Cliquer l'élément par ref du snapshot (ex : @0-5)
browse type <text>                       # Taper du texte dans l'élément actif
browse fill <selector> <value>           # Remplir l'entrée et appuyer sur Entrée
browse select <selector> <values...>     # Sélectionner l'option(s) du dropdown
browse press <key>                       # Appuyer sur la touche (Enter, Tab, Escape, Cmd+A, etc.)
browse drag <fromX> <fromY> <toX> <toY>  # Glisser d'un point à un autre
browse scroll <x> <y> <deltaX> <deltaY> # Faire défiler aux coordonnées
browse highlight <selector>              # Mettre en surbrillance l'élément sur la page
browse is visible <selector>             # Vérifier si l'élément est visible
browse is checked <selector>             # Vérifier si l'élément est coché
browse wait <type> [arg]                 # Attendre : load, selector, timeout

Gestion de session

browse stop                              # Arrêter le daemon du navigateur (efface aussi le remplacément env)
browse status                            # Vérifier le statut du daemon (inclut env)
browse env                               # Afficher l'environnement actuel (local ou remote)
browse env local                         # Utiliser un navigateur local isolé et propre
browse env local --auto-connect          # Réutiliser Chrome existant, basculer à l'isolé
browse env local <port|url>              # Se connecter à une cible CDP spécifique
browse env remote                        # Basculer à Browserbase (nécessite des clés API)
browse pages                             # Lister tous les onglets ouverts
browse tab_switch <index>                # Basculer à l'onglet par index
browse tab_close [index]                 # Fermer l'onglet

Flux de travail typique

Si l'environnement importe, définissez-le d'abord avec browse env local, browse env local --auto-connect, ou browse env remote.

browse open <url> — accédez à la page
browse snapshot — lisez l'arbre d'accessibilité pour comprendre la structure de la page et obtenir les références d'éléments
browse click <ref> / browse type <text> / browse fill <selector> <value> — interagissez en utilisant les refs du snapshot
browse snapshot — confirmez que l'action a fonctionné
Répétez les étapes 3-4 au besoin
browse stop — fermez le navigateur quand vous avez terminé

Exemple rapide

browse open https://example.com
browse snapshot                          # voir la structure de la page + références d'éléments
browse click @0-5                        # cliquer l'élément avec ref 0-5
browse get title
browse stop

Comparaison des modes

Fonctionnalité	Local	Browserbase
Vitesse	Plus rapide	Légèrement plus lent
Configuration	Chrome requis	Clé API requise
Réutiliser les cookies locaux existants	Avec `browse env local --auto-connect`	N/A
Mode furtif	Non	Oui (Chromium personnalisé, anti-bot fingerprinting)
Résolution de CAPTCHA	Non	Oui (reCAPTCHA/hCaptcha automatique)
Proxies résidentiels	Non	Oui (201 pays, géo-ciblage)
Persistance de session	Non	Oui (cookies/auth persistent via contexts)
Idéal pour	Développement/pages simples	Sites protégés, détection de bot, scraping en production

Bonnes pratiques

Choisir la stratégie locale délibérément : utilisez browse env local pour un état propre, browse env local --auto-connect pour les identifiants locaux existants, et browse env remote pour les sites protégés
Toujours exécuter browse open d'abord avant d'interagir
Utiliser browse snapshot pour vérifier l'état de la page — c'est rapide et vous donne les références d'éléments
N'utiliser screenshot que quand le contexte visuel est nécessaire (vérifications de disposition, images, débogage)
Utiliser les refs du snapshot pour cliquer/interagir — ex : browse click @0-5
Exécuter browse stop quand c'est fait pour nettoyer la session du navigateur et effacer le remplacément env

Dépannage

« No active page » : Exécutez browse stop, puis vérifiez browse status. S'il dit toujours en cours d'exécution, tuez le daemon zombie avec pkill -f "browse.*daemon", puis réessayez browse open
Chrome introuvable : Installez Chrome, utilisez browse env local --auto-connect si vous avez déjà un Chrome débogable en cours d'exécution, ou basculez à browse env remote
L'action échoue : Exécutez browse snapshot pour voir les éléments disponibles et leurs refs
Browserbase échoue : Vérifiez que la clé API est définie

Basculer au mode Remote

Basculez au remote quand vous détectez : des CAPTCHA (reCAPTCHA, hCaptcha, Turnstile), des pages de détection de bot (« Vérification de votre navigateur... »), HTTP 403/429, des pages vides sur des sites qui devraient avoir du contenu, ou si l'utilisateur le demande.

Ne basculez pas pour les sites simples (docs, wikis, APIs publiques, localhost).

browse env local             # navigateur local isolé et propre
browse env local --auto-connect  # réutiliser l'état Chrome existant
browse env remote            # basculer à Browserbase

Les remplaçements sont limités par session et restent en effet jusqu'à ce que vous basculiez à nouveau ou exécutiez browse stop. Après browse stop, le prochain démarrage revient à la détection automatique basée sur la variable d'environnement. Utilisez browse status pour inspecter la stratégie locale résolue pendant que le daemon est en cours d'exécution.

Pour des exemples détaillés, voir EXAMPLES.md. Pour la référence API, voir REFERENCE.md.