Browse CLI

Utilisez browse comme interface de ligne de commande principale de Browserbase.

Il peut :

piloter une session de navigateur locale ou hébergée par Browserbase
inspecter les pages via des snapshots d'accessibilité, des captures d'écran, des lectures DOM/texte et la capture réseau
interagir avec les pages par refs, sélecteurs, XPath, clavier, souris, fichiers et contrôles de viewport
gérer les projets, sessions, contextes, extensions Browserbase ainsi que les APIs fetch et search
développer, publier et invoquer Browserbase Functions
parcourir et générer des templates Browserbase
diagnostiquer les problèmes de configuration du navigateur local ou distant
découvrir et installer des skills du catalogue Browse.sh
installer ou actualiser cette skill Browse CLI

Vérification de la configuration

Vérifiez que la CLI existe avant de vous y fier :

which browse || npm install -g browse
browse --help

Installez ou actualisez cette skill avec :

browse skills install

Utilisez browse <topic> --help pour connaître les flags exacts avant d'exécuter des commandes inconnues.

Sélection de la cible du navigateur

Les commandes de pilotage du navigateur démarrent automatiquement le daemon browse si nécessaire. Choisissez la cible du navigateur par commande avec des flags :

browse open https://example.com --local
browse open https://example.com --local --headed
browse open https://example.com --remote
browse open https://example.com --remote --verified --proxies
browse open https://example.com --auto-connect
browse open https://example.com --cdp 9222
browse open https://example.com --cdp ws://127.0.0.1:9222/devtools/browser/<id>

Utilisez le mode local pour le développement, localhost, les sites de confiance et les itérations rapides. Utilisez --auto-connect uniquement quand l'utilisateur souhaite explicitement se connecter à une session Chrome débogage déjà en cours avec des cookies ou un état de connexion existants ; utilisez --local quand aucun Chrome débogage n'est disponible. Utilisez le mode distant quand les identifiants Browserbase sont disponibles et que le site nécessite une infrastructure de navigateur hébergée, le mode navigateur Verified, la résolution de CAPTCHA, des proxies ou la persistance de session.

Pour une session distante Verified et/ou avec proxies, ajoutez --verified et/ou --proxies à --remote — une seule commande qui conserve l'identité de session Browserbase, de sorte que browse status et browse doctor rapportent l'ID de session et l'URL de live-view. --verified nécessite un plan Browserbase Scale. Ces flags ne s'appliquent qu'à --remote et sont persistants pour la durée de vie de la session, comme --headed. N'utilisez browse cloud sessions create + --cdp que quand vous avez besoin d'options de session que open n'expose pas (région, keep-alive, contextes).

Choisissez les modes headed/headless et local/remote au démarrage d'une session. Une session en cours conserve son mode : passer un flag conflictuel comme --headed à une session headless déjà en cours échoue jusqu'à ce que vous exécutiez browse stop --session <name> ou que vous cibliez une session différente.

Utilisez des sessions nommées pour tout travail non trivial, en particulier quand plusieurs agents ou tâches parallèles pourraient s'exécuter simultanément. Toute commande de navigateur accepte --session <name> (ou -s <name>) ; la variable d'environnement BROWSE_SESSION définit la valeur par défaut, et les commandes sans l'une ou l'autre partagent la session default.

browse open https://example.com --session research --local
browse snapshot --session research

Les commandes de navigateur distant et les APIs cloud nécessitent :

export BROWSERBASE_API_KEY=...

Flux de travail d'automatisation du navigateur

Commencez par ouvrir la page, puis inspectez l'état, agissez et vérifiez.

browse open https://example.com --session research --local
browse snapshot --session research
browse click @0-5 --session research
browse type "hello" --session research
browse snapshot --session research
browse stop --session research

Préférez browse snapshot aux captures d'écran pour la plupart des travaux de navigateur. C'est structuré, rapide et retourne des refs comme @0-5 pour une interaction fiable avec les éléments. Utilisez les captures d'écran quand la mise en page visuelle, les images ou l'état au niveau des pixels importent.

Les refs sont actualisées à chaque snapshot. Après des clics, des soumissions de formulaire, une navigation ou des re-rendus d'interface, prenez un nouveau snapshot avant d'utiliser une autre ref.

Travail de navigateur parallèle

Utilisez une valeur --session différente pour chaque tâche de navigateur indépendante. Les sessions isolent les onglets, les cookies, les refs et l'état du daemon ; les tâches parallèles qui omettent --session partagent la session default et écrasent la page active l'une de l'autre.

browse open https://example.com/search-a --session search-a --local
browse open https://example.com/search-b --session search-b --local
browse snapshot --session search-a
browse snapshot --session search-b

Quand une tâche est terminée, arrêtez uniquement la session de cette tâche :

browse stop --session search-a

Commandes principales du navigateur

Navigation :

browse open <url>
browse reload
browse back
browse forward
browse wait load
browse wait selector "#result"

État de la page :

browse snapshot
browse snapshot --compact
browse get url
browse get title
browse get text body
browse get html "#main"
browse get value "#email"
browse get markdown body                   # contenu de page/élément en markdown
browse eval "document.title"              # exécuter du JavaScript dans la page active
browse screenshot                         # enregistre screenshot-<timestamp>.png, affiche { "saved": "<path>" }
browse screenshot --path page.png         # choisir le chemin de sortie
browse screenshot --base64                # hérité : afficher JSON base64 sur stdout (éviter dans les boucles d'agent)

Interaction :

browse click @0-5
browse fill @0-8 "search query"
browse type "text for the focused element"
browse press Enter
browse select "select[name=country]" "United States"
browse upload @0-12 ./file.pdf
browse highlight @0-5
browse is visible "#modal"

Souris et viewport :

browse mouse click 240 320
browse mouse hover 240 320
browse mouse drag 80 80 310 100
browse mouse scroll 500 300 0 600
browse viewport 1280 720
browse cursor                             # afficher un curseur visible en overlay

Onglets, réseau et CDP :

browse tab list
browse tab new https://example.com
browse tab switch <target-id>
browse tab close <target-id>              # refuse de fermer le dernier onglet
browse network on
browse network off
browse network path
browse network clear
browse cdp 9222 --pretty

Gestion de session :

browse doctor
browse doctor --json
browse status
browse stop
browse stop --force

Utilisez browse doctor avant de déboguer une session de navigateur cassée. Utilisez browse doctor --json quand un autre agent ou une CI nécessite des diagnostics structurés.

Si une commande de page rapporte qu'aucune page active n'est disponible, inspectez et récupérez la session nommée :

browse status --session research
browse tab list --session research
browse tab new https://example.com --session research
browse open https://example.com --session research

APIs cloud

Utilisez browse cloud pour les APIs de plateforme Browserbase :

browse cloud projects list
browse cloud projects get <project-id>
browse cloud projects usage <project-id>
browse cloud sessions create
browse cloud sessions create --proxies --verified
browse cloud sessions list
browse cloud sessions get <session-id>
browse cloud sessions update <session-id>
browse cloud sessions debug <session-id>
browse cloud sessions logs <session-id>
browse cloud sessions downloads get <session-id>
browse cloud sessions uploads create <session-id> ./file.pdf
browse cloud contexts create --name github
browse cloud contexts add github <context-id>
browse cloud contexts list
browse cloud contexts get <context-id|name>
browse cloud contexts update <context-id|name>
browse cloud contexts delete <context-id|name>
browse cloud extensions upload ./extension.zip
browse cloud extensions get <extension-id>
browse cloud extensions delete <extension-id>
browse cloud fetch https://example.com
browse cloud search "browser automation"

Pour les sessions distantes avec persistance de contexte :

browse cloud sessions create --context-id <context-id> --persist

Les contextes persistent les cookies et le stockage local (connexions) entre les sessions. Nommez un contexte une fois avec --name pour enregistrer un alias local, puis réutilisez le nom partout où un ID de contexte est accepté au lieu de mémoriser l'ID :

browse cloud contexts create --name github          # enregistre github -> ctx_...
browse cloud contexts add github <context-id>        # nommer un contexte que vous avez déjà
browse cloud sessions create --context-id github --persist
browse cloud contexts list                          # afficher les noms enregistrés

Utilisez --verified quand la tâche nécessite le mode navigateur Browserbase Verified. Pour piloter directement une session Verified/avec proxies, préférez browse open <url> --remote --verified --proxies à create-then-attach — cela conserve l'identité de session de sorte que browse status/browse doctor puisse la rapporter. Utilisez browse cloud sessions create pour les options de session que les flags du driver ne couvrent pas (région, keep-alive, contextes, corps --stdin complet).

Utilisez browse cloud fetch quand l'utilisateur a besoin d'une simple requête HTTP sans interaction du navigateur. Il retourne du contenu de page au format markdown par défaut ; passez --format raw pour le corps de réponse original ou --format json --schema <schema> pour l'extraction structurée. Utilisez browse cloud search quand l'utilisateur demande des résultats de recherche web.

Browserbase Functions

Utilisez browse functions pour créer, développer, publier et invoquer des Browserbase Functions :

browse functions init my-function
browse functions dev index.ts
browse functions publish index.ts
browse functions publish index.ts --dry-run
browse functions invoke <function-id> --params '{"url":"https://example.com"}'
browse functions invoke --check-status <invocation-id>

Les commandes functions utilisent BROWSERBASE_API_KEY. Les projets générés importent defineFn depuis @browserbasehq/sdk-functions.

Templates

Utilisez browse templates pour découvrir et générer des templates de démarrage Browserbase :

browse templates list
browse templates list --tag Python --source Browserbase
browse templates find google-trends-keywords
browse templates find amazon --json
browse templates clone google-trends-keywords
browse templates clone amazon-product-scraping --language python ./my-scraper
browse templates clone dynamic-form-filling ./form-bot --language typescript

Utilisez browse templates find avant de cloner quand le slug exact est incertain. Utilisez --language typescript ou --language python pour choisir le runtime du projet généré quand un template supporte les deux.

Skills

Installez ou actualisez cette skill CLI groupée :

browse skills install

Découvrir les skills Browse.sh

Browse.sh (https://browse.sh) est un catalogue de skills d'automatisation de navigateur spécifiques aux sites. Chaque skill est limitée à une tâche sur un seul site et identifiée par un slug <domain>/<task>. Une skill installée encode une stratégie éprouvée pour ce site — endpoints API, sélecteurs, gestion anti-bot — de sorte qu'elle complète la tâche plus rapidement et de manière plus fiable qu'en explorant le site à partir de zéro.

Recherchez le catalogue proactivement quand :

l'utilisateur demande de compléter une tâche sur un site spécifique — recherchez le domaine avant de l'automatiser à la main
l'utilisateur demande une tâche dans une catégorie courante comme vols, livraison de nourriture, avis, recettes, billets, emplois ou achats — recherchez le mot-clé
l'utilisateur demande « y a-t-il une skill pour X » ou souhaite de nouvelles capacités

browse skills list                              # parcourir le catalogue
browse skills find <query>                      # rechercher par slug, domaine, titre, description, catégorie, alias ou tag
browse skills add <domain>/<task>               # installer un slug exact

Stratégie de recherche

Recherchez d'abord le domaine, puis la tâche, puis élargissez :

browse skills find yelp.com                     # 1. domaine exact
browse skills find yelp                         # 2. nom du site
browse skills find reviews                      # 3. mot-clé de tâche
browse skills find "restaurant reviews"         # 4. requête multi-mots
browse skills find food --limit 5               # 5. mot-clé de catégorie, limité

Interroger un slug exact (browse skills find yelp.com/extract-reviews-2ikb22) affiche une vue détaillée avec la description complète et la commande d'installation.
Si une recherche ne retourne rien, essayez des synonymes (flights vs travel, food vs restaurants) avant de conclure qu'aucune skill n'existe.
Chaque résultat affiche une méthode recommandée — api, fetch, browser ou hybrid — indiquant comment la skill pilote le site. Les compteurs d'installation signalent quelles skills sont éprouvées.
De nombreux slugs se terminent par un suffixe généré (-2ikb22), donc ne les devinez jamais ou ne les construisez pas. Installez uniquement avec un slug exact copié depuis la sortie list ou find : browse skills add yelp.com/extract-reviews-2ikb22. La skill installée devient disponible pour l'agent en tant que skill ordinaire ; une nouvelle session d'agent peut être nécessaire pour la prendre en compte.

Formats de sortie

La sortie est un tableau dans un terminal et du JSON quand piped, donc les agents obtiennent du JSON structuré par défaut. Forcez un format avec --format table|json ou --json.

browse skills find food --format table --limit 10
browse skills find food --json | jq -r '.skills[] | "\(.slug)\t\(.title)"'

La sortie JSON inclut tous les correspondances avec des descriptions complètes et ignore --limit ; browse skills list --json retourne le catalogue entier, qui est volumineux. Préférez browse skills find <query> pour réduire d'abord, ou --format table --limit <n> pour une vue compacte.

Bonnes pratiques

Exécutez la commande réelle et inspectez sa sortie au lieu de deviner.
Utilisez browse snapshot avant d'interagir de sorte que vous ayez des refs actuelles.
Réexécutez browse snapshot après la navigation ou les actions changeant le DOM car les refs peuvent changer.
Préférez les refs des snapshots pour les clics et les uploads ; utilisez les sélecteurs ou XPath quand les refs ne sont pas disponibles.
Utilisez --local pour localhost et le développement répétable ; utilisez --remote pour les sites protégés ou le comportement spécifique à Browserbase.
Utilisez un --session <name> distinct pour chaque tâche parallèle ou longue durée ; les commandes sans ce flag partagent la session default.
Utilisez --auto-connect uniquement quand l'intention est de se connecter à une session Chrome débogage locale existante.
Utilisez browse doctor quand le démarrage de session, la découverte de navigateur, l'attachement CDP ou l'authentification Browserbase semble erronée.
Ne réessayez jamais une commande défaillante inchangée. Si la même commande échoue deux fois avec la même erreur, arrêtez — exécutez browse doctor --json, puis changez d'approche (corrigez la clé, basculez --local/--remote, ou browse stop --force et recommencez). Répéter une commande défaillante identique continuera d'échouer.
Utilisez browse stop (ou browse stop --session <name>) quand vous avez terminé pour nettoyer l'état du daemon.
Pour des détails de commande inconnue, exécutez browse <topic> --help et suivez les flags exacts en dash-case.

Dépannage

« Aucune page active » : exécutez browse status --session <name>, puis browse open <url> --session <name> ou browse tab new <url> --session <name> ; utilisez browse stop --force si le daemon est périmé.
Chrome non trouvé : utilisez --remote avec les identifiants Browserbase, installez Chrome, ou attachez-vous avec --cdp.
L'action échoue : exécutez browse snapshot et utilisez une ref visible depuis l'état actuel de la page.
401 Unauthorized sur open, get ou d'autres commandes du driver : un BROWSERBASE_API_KEY défini fait que browse bascule par défaut en mode distant. Corrigez la clé sur https://browserbase.com/settings, défilez-la, ou passez --local pour exécuter un navigateur local géré (aucune clé nécessaire).
La même commande échoue deux fois avec la même erreur : arrêtez de réessayer — ne réessayez jamais une commande défaillante inchangée. Les échecs d'initialisation sont mis en cache pendant plusieurs secondes, donc les réessais instantanés retournent des erreurs identiques. Exécutez browse doctor --json, puis changez d'approche : corrigez la clé, basculez --local/--remote, ou browse stop --force et recommencez.
La commande distante échoue : vérifiez BROWSERBASE_API_KEY et inspectez browse cloud projects list.
La configuration de session est floue : exécutez browse doctor ou browse doctor --json.
Le site protégé bloque le mode local : réessayez avec --remote.
browse skills find ne retourne rien : élargissez la requête — domaine nu, puis nom du site, puis un mot-clé de tâche ou un synonyme.
browse skills add échoue sur npx : installez Node.js depuis https://nodejs.org, puis réexécutez.
La skill nouvellement ajoutée n'est pas disponible : elle s'installe pour les futures sessions ; listez les skills installées ou démarrez une nouvelle session d'agent.