> ## Documentation Index
> Fetch the complete documentation index at: https://gologin.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gologin Agent Browser CLI

> CLI d'automatisation de navigateur cloud conçue pour les agents IA, avec snapshots, refs et un daemon persistant

Gologin Agent Browser CLI transforme Gologin Cloud Browser en environnement d'exécution persistant et scriptable pour les agents IA. Il fournit des snapshots de page compacts, des interactions basées sur des refs, une mémoire de session et une sortie adaptée au shell.

Contrairement à l'écriture de code Puppeteer/Playwright à partir de zéro, cette CLI offre aux agents un ensemble de commandes prêt à l'emploi pour l'automatisation du navigateur, sans code superflu ni code de gestion de session.

***

## Pourquoi un navigateur cloud

L'automatisation avec un navigateur local présente des limites importantes pour les workflows d'agents :

* Les navigateurs locaux sont plus faciles à détecter
* Aucune empreinte numérique basée sur des profils
* Aucun profil de navigateur cloud persistant
* Aucune couche proxy intégrée
* Difficile à standardiser entre les agents et les environnements

Agent Browser CLI adopte l'approche inverse :

* Un environnement d'exécution de navigateur cloud au lieu d'un processus local
* Les profils Gologin comme couche d'identité de session
* Des sessions compatibles avec les proxys
* Les capacités anti-détection héritées de Gologin
* Un daemon persistant qui maintient les sessions actives entre les appels de la CLI

***

## Installation

```bash theme={null}
npm install -g gologin-agent-browser-cli
```

Ou exécutez-la sans installation globale :

```bash theme={null}
npx gologin-agent-browser-cli --help
```

Nécessite Node.js >= 18.

***

## Identifiants

| Variable | Obligatoire | Description |
| - | - | - |
| `GOLOGIN_TOKEN` | Oui (pour `open`) | Jeton d'API Gologin |
| `GOLOGIN_PROFILE_ID` | Facultatif | ID du profil par défaut |
| `GOLOGIN_DAEMON_PORT` | Facultatif | Port du daemon (par défaut : `44777`) |
| `GOLOGIN_CONNECT_BASE` | Facultatif | Point de terminaison de Cloud Browser |

### Obtenir un jeton

1. Inscrivez-vous ou connectez-vous sur [gologin.com](https://gologin.com)
2. Ouvrez **API & MCP** dans le tableau de bord
3. Ouvrez l'onglet **API**
4. Cliquez sur **Nouveau jeton**
5. Copiez le jeton d'accès généré

```bash theme={null}
export GOLOGIN_TOKEN='your_gologin_token'
```

### Fichier de configuration

`~/.gologin-agent-browser/config.json`

***

## Architecture

Deux composants :

1. **CLI `gologin-agent-browser`** : analyse les commandes, démarre automatiquement le daemon et affiche une sortie compacte
2. **Daemon local persistant** : gère les sessions de navigateur actives, se connecte à Gologin Cloud Browser via `connectOverCDP` de Playwright, conserve la page active en mémoire, génère les snapshots, résout les refs et suit les métadonnées de session

Le transport est uniquement local :

* Socket Unix à l'emplacement `${TMPDIR:-/tmp}/gologin-agent-browser.sock`
* HTTP en localhost sur `127.0.0.1:${GOLOGIN_DAEMON_PORT:-44777}`

Si vous ne fournissez pas d'ID de profil, le daemon crée un profil cloud Gologin temporaire via l'API.

***

## Fonctionnement des refs

`snapshot` affiche une vue compacte de la page et attribue des refs comme `@e1`, `@e2`, `@e3` aux éléments interactifs. Vous agissez directement sur ces éléments :

```bash theme={null}
gologin-agent-browser snapshot
# output shows page content with refs like @e1, @e2, @e3...

gologin-agent-browser click @e3
gologin-agent-browser type @e5 "search query"
gologin-agent-browser fill @e7 "username"
```

Les refs sont fournies au mieux et doivent être régénérées après une navigation ou une modification importante du DOM. Sur les pages dynamiques, `find` est généralement une meilleure solution de repli que des refs obsolètes.

***

## Démarrage rapide

```bash theme={null}
export GOLOGIN_TOKEN='your_token'

# open a page in cloud browser
gologin-agent-browser open https://example.com

# read the page as a compact snapshot
gologin-agent-browser snapshot

# interact with elements
gologin-agent-browser click @e3
gologin-agent-browser type @e5 "hello world"

# take a screenshot
gologin-agent-browser screenshot ./page.png

# close the session
gologin-agent-browser close
```

***

## Exemple de boucle d'agent

Une boucle typique pour un agent IA :

```
1. open <url>
2. snapshot          → agent reads page content
3. click/type/fill   → agent acts on refs
4. snapshot          → agent reads result
5. repeat 3-4 as needed
6. screenshot        → save artifact
7. close
```

***

## Référence complète des commandes

### Diagnostic

| Commande | Description |
| - | - |
| `doctor` | Vérifier l'état et la connectivité du daemon |

### Gestion des sessions

| Commande | Description |
| - | - |
| `open <url>` | Ouvrir une URL dans une session de navigateur cloud |
| `close` | Fermer la session en cours |
| `sessions` | Lister les sessions actives |
| `current` | Afficher les informations de la session en cours |

### Lecture de la page

| Commande | Description |
| - | - |
| `snapshot` | Snapshot texte compact avec les refs des éléments |
| `screenshot <path>` | Enregistrer une capture d'écran de la page |
| `pdf <path>` | Enregistrer la page au format PDF |
| `get <kind> [target]` | Obtenir les propriétés de la page |

### Interaction

| Commande | Description |
| - | - |
| `click <ref>` | Cliquer sur un élément |
| `dblclick <ref>` | Double-cliquer |
| `type <ref> <text>` | Saisir du texte (ajoute à l'existant) |
| `fill <ref> <text>` | Remplir un champ (remplace le contenu) |
| `hover <ref>` | Survoler un élément |
| `select <ref> <value>` | Sélectionner une valeur dans une liste déroulante |
| `check <ref>` / `uncheck <ref>` | Cocher ou décocher une case |
| `focus <ref>` | Mettre le focus sur un élément |
| `find ...` | Recherche sémantique d'éléments |

### Clavier et défilement

| Commande | Description |
| - | - |
| `press <key> [target]` | Appuyer sur une touche du clavier |
| `scroll <direction> [pixels]` | Faire défiler la page |
| `scrollintoview <ref>` | Faire défiler jusqu'à rendre l'élément visible |

### Navigation

| Commande | Description |
| - | - |
| `back` | Revenir en arrière |
| `forward` | Avancer |
| `reload` | Recharger la page |
| `wait <target\|ms>` | Attendre un élément ou un délai |

### Onglets

| Commande | Description |
| - | - |
| `tabs` | Lister les onglets ouverts |
| `tabopen [url]` | Ouvrir un nouvel onglet |
| `tabfocus <index>` | Passer à un onglet |
| `tabclose [index]` | Fermer un onglet |

### Cookies et stockage

| Commande | Description |
| - | - |
| `cookies` | Exporter les cookies |
| `cookies-import <file>` | Importer des cookies |
| `cookies-clear` | Supprimer les cookies |
| `storage-export [path]` | Exporter le localStorage |
| `storage-import <file>` | Importer le localStorage |
| `storage-clear` | Vider le localStorage |

### Avancé

| Commande | Description |
| - | - |
| `eval <expression>` | Évaluer du JavaScript dans la page |
| `upload <ref> <file...>` | Téléverser des fichiers |

### Alias

| Alias | Correspond à |
| - | - |
| `goto`, `navigate` | `open` |
| `tabnew` | `tabopen` |
| `tabswitch` | `tabfocus` |
| `js` | `eval` |
| `key` | `press` |
| `scrollinto` | `scrollintoview` |
| `quit`, `exit` | `close` |

***

## Cas d'usage et exemples

### Vérifier si votre site réussit les tests anti-détection

```bash theme={null}
gologin-agent-browser open https://iphey.com/ --profile your_profile_id
gologin-agent-browser wait 3000
gologin-agent-browser snapshot     # read the trust score
gologin-agent-browser screenshot ./iphey-result.png
gologin-agent-browser close
```

### Se connecter à une application web et extraire les données du tableau de bord

```bash theme={null}
gologin-agent-browser open https://app.example.com/login
gologin-agent-browser snapshot

# agent reads snapshot, finds login form
gologin-agent-browser fill @e4 "user@company.com"
gologin-agent-browser fill @e6 "password"
gologin-agent-browser click @e8

gologin-agent-browser wait 3000
gologin-agent-browser snapshot     # agent reads dashboard content

# navigate to the report page
gologin-agent-browser click @e12   # "Reports" link
gologin-agent-browser wait 2000
gologin-agent-browser snapshot     # agent extracts report data
gologin-agent-browser screenshot ./report.png
gologin-agent-browser close
```

### Remplir un formulaire en plusieurs étapes

```bash theme={null}
gologin-agent-browser open https://forms.example.com/apply

# step 1: personal info
gologin-agent-browser snapshot
gologin-agent-browser fill @e3 "John Doe"
gologin-agent-browser fill @e5 "john@example.com"
gologin-agent-browser select @e7 "United States"
gologin-agent-browser click @e9   # Next

# step 2: upload and submit
gologin-agent-browser wait 1000
gologin-agent-browser snapshot
gologin-agent-browser upload @e4 ./resume.pdf
gologin-agent-browser check @e6   # agree to terms
gologin-agent-browser click @e8   # Submit

gologin-agent-browser wait 2000
gologin-agent-browser snapshot     # confirm success
gologin-agent-browser close
```

### Faire des captures d'écran des pages de concurrents

```bash theme={null}
# use different profiles with different geos
for profile in us_profile de_profile jp_profile; do
  gologin-agent-browser open https://competitor.com --profile $profile
  gologin-agent-browser wait 3000
  gologin-agent-browser screenshot ./${profile}-homepage.png
  gologin-agent-browser close
done
```

### Effectuer une recherche sur un site qui bloque le scraping

Certains sites exigent l'exécution de JavaScript, une connexion ou une interaction avant d'afficher les résultats. Utilisez le navigateur pour effectuer la recherche :

```bash theme={null}
gologin-agent-browser open https://protected-directory.com
gologin-agent-browser snapshot
gologin-agent-browser find "search input"
gologin-agent-browser type @found "machine learning engineer San Francisco"
gologin-agent-browser press Enter
gologin-agent-browser wait 3000
gologin-agent-browser snapshot     # agent reads search results
gologin-agent-browser screenshot ./search-results.png
gologin-agent-browser close
```

### Enregistrer et restaurer l'état d'une session

Exportez les cookies et le stockage pour les réutiliser d'une session à l'autre :

```bash theme={null}
# after logging in
gologin-agent-browser cookies --output ./session-cookies.json
gologin-agent-browser storage-export ./session-storage.json
gologin-agent-browser close

# later, restore the session
gologin-agent-browser open https://app.example.com
gologin-agent-browser cookies-import ./session-cookies.json
gologin-agent-browser storage-import ./session-storage.json
gologin-agent-browser reload
gologin-agent-browser snapshot     # already logged in
```

***

## Sessions parallèles

Utilisez des ID `--session` explicites pour des tâches cloud indépendantes. Nettoyez avec `close --all` ou `sessions --prune --older-than-ms`.

***

## Règles relatives aux proxys

* Profils préconfigurés : le proxy est défini sur le profil via le tableau de bord ou l'API de Gologin
* Profils temporaires : prennent en charge l'absence de proxy ou un hôte/port de proxy personnalisé
* `--proxy-country` n'est disponible que pour les profils préconfigurés

***

## Voir aussi

* [Gologin Web Access CLI](https://gologin.com/docs/fr/cli-tools/web-access.md) : CLI unifiée (scraping + navigateur)
* [Local Agent Browser CLI](https://gologin.com/docs/fr/cli-tools/local-agent-browser.md) : alternative locale avec Orbita
* [Premiers pas avec Cloud Browser](https://gologin.com/docs/fr/api-reference/cloud-browser/getting-started.md) : exemples Puppeteer/Playwright
* [AI Skills](https://gologin.com/docs/fr/api-reference/ai-integrations/ai-skills.md) : skills prêts à l'emploi pour Claude Code

> **[Package npm](https://www.npmjs.com/package/gologin-agent-browser-cli)**
>
> gologin-agent-browser-cli

> **[Code source](https://github.com/GologinLabs/agent-browser)**
>
> GologinLabs/agent-browser


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.