Automation de navigateur avec browser-use CLI

La commande browser-use offre une automation de navigateur rapide et persistante. Un daemon en arrière-plan maintient le navigateur ouvert entre les commandes, donnant ~50ms de latence par appel.

Prérequis

browser-use doctor    # Vérifier l'installation

Pour les détails de configuration, voir https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Flux de travail principal

Naviguer : browser-use open <url> — lance le navigateur headless et ouvre la page
Inspecter : browser-use state — retourne les éléments cliquables avec indices
Interagir : utiliser les indices de state (browser-use click 5, browser-use input 3 "text")
Vérifier : browser-use state ou browser-use screenshot pour confirmer
Répéter : le navigateur reste ouvert entre les commandes

Si une commande échoue, exécutez d'abord browser-use close pour effacer toute session cassée, puis réessayez.

Pour utiliser le Chrome existant de l'utilisateur (conserve les logins/cookies) : exécutez d'abord browser-use connect. Pour utiliser un navigateur cloud à la place : exécutez d'abord browser-use cloud connect. Après l'un ou l'autre, les commandes fonctionnent de la même manière.

Si `browser-use connect` échoue

Quand browser-use connect ne peut pas trouver un Chrome en cours d'exécution avec débogage distant, proposez à l'utilisateur deux options :

Utiliser leur vrai navigateur Chrome — ils doivent d'abord activer le débogage distant :
- Ouvrir chrome://inspect/#remote-debugging dans Chrome, ou relancer Chrome avec --remote-debugging-port=9222
- Puis réessayer browser-use connect
Utiliser Chromium géré avec leur profil Chrome — aucune configuration Chrome nécessaire :
- Exécutez browser-use profile list pour montrer les profils disponibles
- Demandez quel profil ils veulent, puis utilisez browser-use --profile "ProfileName" open <url>
- Cela lance une instance Chromium séparée avec leurs données de profil (cookies, logins, extensions)

Laissez l'utilisateur choisir — ne supposez pas un chemin plutôt que l'autre.

Modes de navigateur

browser-use open <url>                         # Par défaut : Chromium headless (aucune configuration nécessaire)
browser-use --headed open <url>                # Fenêtre visible (pour le débogage)
browser-use connect                            # Se connecter au Chrome de l'utilisateur (conserve logins/cookies)
browser-use cloud connect                      # Navigateur cloud (zéro config, nécessite une clé API)
browser-use --profile "Default" open <url>     # Vrai Chrome avec un profil spécifique

Après connect ou cloud connect, tous les commandes suivantes vont vers ce navigateur — aucun flag supplémentaire nécessaire.

Commandes

# Navigation
browser-use open <url>                    # Naviguer vers l'URL
browser-use back                          # Retour dans l'historique
browser-use scroll down                   # Défiler vers le bas (--amount N pour pixels)
browser-use scroll up                     # Défiler vers le haut
browser-use tab list                      # Lister tous les onglets
browser-use tab new [url]                 # Ouvrir un nouvel onglet (vide ou avec URL)
browser-use tab switch <index>            # Basculer vers l'onglet par index
browser-use tab close <index> [index...]  # Fermer un ou plusieurs onglets

# État de la page — toujours exécuter state en premier pour obtenir les indices d'éléments
browser-use state                         # URL, titre, éléments cliquables avec indices
browser-use screenshot [path.png]         # Capture d'écran (base64 si pas de chemin, --full pour page entière)

# Interactions — utiliser les indices de state
browser-use click <index>                 # Cliquer sur l'élément par index
browser-use click <x> <y>                 # Cliquer aux coordonnées en pixels
browser-use type "text"                   # Taper dans l'élément actif
browser-use input <index> "text"          # Cliquer sur l'élément, effacer le texte existant, puis taper
browser-use input <index> ""              # Vider un champ sans taper de nouveau texte
browser-use keys "Enter"                  # Envoyer des touches clavier (aussi "Control+a", etc.)
browser-use select <index> "option"       # Sélectionner une option de dropdown
browser-use upload <index> <path>         # Télécharger un fichier vers un input fichier
browser-use hover <index>                 # Survoler l'élément
browser-use dblclick <index>              # Double-cliquer sur l'élément
browser-use rightclick <index>            # Clic droit sur l'élément

# Extraction de données
browser-use eval "js code"                # Exécuter du JavaScript, retourner le résultat
browser-use get title                     # Titre de la page
browser-use get html [--selector "h1"]    # HTML de la page (ou limité au sélecteur)
browser-use get text <index>              # Contenu texte de l'élément
browser-use get value <index>             # Valeur input/textarea
browser-use get attributes <index>        # Attributs de l'élément
browser-use get bbox <index>              # Boîte englobante (x, y, largeur, hauteur)

# Attendre
browser-use wait selector "css"           # Attendre un élément (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Attendre qu'un texte apparaisse

# Cookies
browser-use cookies get [--url <url>]     # Obtenir les cookies (optionnellement filtrés)
browser-use cookies set <name> <value>    # Définir un cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Effacer les cookies
browser-use cookies export <file>         # Exporter en JSON
browser-use cookies import <file>         # Importer depuis JSON

# Session
browser-use close                         # Fermer le navigateur et arrêter le daemon
browser-use sessions                      # Lister les sessions actives
browser-use close --all                   # Fermer toutes les sessions

Pour un contrôle avancé du navigateur (CDP, émulation d'appareil, activation d'onglet), voir references/cdp-python.md.

API Cloud

browser-use cloud connect                 # Provisionner un navigateur cloud et se connecter (zéro config)
browser-use cloud login <api-key>         # Enregistrer la clé API (ou définir BROWSER_USE_API_KEY)
browser-use cloud logout                  # Supprimer la clé API
browser-use cloud v2 GET /browsers        # Passthrough REST (v2 ou v3)
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>       # Interroger la tâche jusqu'à la fin
browser-use cloud v2 --help               # Afficher les endpoints API

cloud connect provisionne un navigateur cloud avec un profil persistant (créé automatiquement à la première utilisation), se connecte via CDP, et affiche une URL en direct. browser-use close déconnecte ET arrête le navigateur cloud. Pour les paramètres de navigateur personnalisés (proxy, timeout, profil spécifique), utilisez directement cloud v2 POST /browsers avec les paramètres souhaités.

Auto-enregistrement d'agent

Utilisez ceci uniquement si vous n'avez pas déjà une clé API (vérifiez browser-use doctor pour voir si api_key est définie). Si déjà connecté, ignorez entièrement cette section.

browser-use cloud signup — obtenir un défi
Résoudre le défi
browser-use cloud signup --verify <challenge-id> <answer> — vérifier et enregistrer la clé API
browser-use cloud signup --claim — générer une URL pour qu'un humain réclame le compte

Tunnels

browser-use tunnel <port>                 # Démarrer un tunnel Cloudflare (idempotent)
browser-use tunnel list                   # Afficher les tunnels actifs
browser-use tunnel stop <port>            # Arrêter le tunnel
browser-use tunnel stop --all             # Arrêter tous les tunnels

Gestion des profils

browser-use profile list                  # Lister les navigateurs et profils détectés
browser-use profile sync --all            # Synchroniser les profils vers le cloud
browser-use profile update                # Télécharger/mettre à jour le binaire profile-use

Chaînage de commandes

Les commandes peuvent être chaînées avec &&. Le navigateur persiste via le daemon, donc le chaînage est sûr et efficace.

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

Chaînez quand vous n'avez pas besoin de sortie intermédiaire. Exécutez séparément quand vous avez besoin d'analyser state pour découvrir d'abord les indices.

Flux de travail courants

Navigation authentifiée

Quand une tâche nécessite un site authentifié (Gmail, GitHub, outils internes), utilisez les profils Chrome :

browser-use profile list                           # Vérifier les profils disponibles
# Demander à l'utilisateur quel profil utiliser, puis :
browser-use --profile "Default" open https://github.com  # Déjà connecté

Exposer les serveurs de développement local

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Parcourir le tunnel

Navigateurs multiples

Pour les workflows d'agent secondaire ou exécuter plusieurs navigateurs en parallèle, utilisez --session NAME. Chaque session obtient son propre navigateur. Voir references/multi-session.md.

Configuration

browser-use config list                            # Afficher toutes les valeurs de configuration
browser-use config set cloud_connect_proxy jp      # Définir une valeur
browser-use config get cloud_connect_proxy         # Obtenir une valeur
browser-use config unset cloud_connect_timeout     # Supprimer une valeur
browser-use doctor                                 # Affiche la configuration + diagnostics
browser-use setup                                  # Configuration post-installation interactive

Configuration stockée dans ~/.browser-use/config.json.

Options globales

Option	Description
`--headed`	Afficher la fenêtre du navigateur
`--profile [NAME]`	Utiliser le vrai Chrome (bare `--profile` utilise "Default")
`--cdp-url <url>`	Se connecter via URL CDP (`http://` ou `ws://`)
`--session NAME`	Cibler une session nommée (par défaut : "default")
`--json`	Sortie au format JSON
`--mcp`	Exécuter en tant que serveur MCP via stdin/stdout

Conseils

Toujours exécuter state d'abord pour voir les éléments disponibles et leurs indices
Utiliser --headed pour le débogage pour voir ce que fait le navigateur
Les sessions persistent — le navigateur reste ouvert entre les commandes
Alias CLI : bu, browser, et browseruse fonctionnent tous
Si les commandes échouent, exécutez d'abord browser-use close, puis réessayez

Dépannage

Le navigateur ne démarre pas ? browser-use close puis browser-use --headed open <url>
Élément non trouvé ? browser-use scroll down puis browser-use state
Exécuter les diagnostics : browser-use doctor

Nettoyage

browser-use close                         # Fermer la session du navigateur
browser-use tunnel stop --all             # Arrêter les tunnels (si présents)