> ## 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

> Narzędzie CLI do automatyzacji przeglądarki w chmurze, stworzone dla agentów AI, z migawkami stron, referencjami elementów i trwałym demonem

Gologin Agent Browser CLI zamienia Gologin Cloud Browser w trwałe środowisko uruchomieniowe, którym można sterować za pomocą skryptów i które jest przeznaczone dla agentów AI. Udostępnia zwięzłe migawki stron, interakcję opartą na referencjach, pamięć sesji oraz dane wyjściowe przyjazne dla powłoki.

W odróżnieniu od pisania kodu w Puppeteer/Playwright od zera, to narzędzie CLI daje agentom gotowy zestaw poleceń do automatyzacji przeglądarki — bez zbędnego kodu startowego i bez kodu do zarządzania sesjami.

***

## Dlaczego przeglądarka w chmurze

Automatyzacja w lokalnej przeglądarce ma poważne ograniczenia w przepływach pracy agentów:

* Lokalne przeglądarki łatwiej wykryć
* Brak fingerprintingu opartego na profilach
* Brak trwałych profili przeglądarki w chmurze
* Brak wbudowanej warstwy proxy
* Trudno ujednolicić działanie w różnych agentach i środowiskach

Agent Browser CLI przyjmuje odwrotne podejście:

* Przeglądarka działa w chmurze, a nie jako proces lokalny
* Profile Gologin pełnią rolę warstwy tożsamości sesji
* Sesje obsługują proxy
* Możliwości anti-detect są odziedziczone z Gologin
* Trwały demon utrzymuje sesje aktywne pomiędzy kolejnymi wywołaniami CLI

***

## Instalacja

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

Lub uruchom bez instalacji globalnej:

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

Wymagany jest Node.js >= 18.

***

## Dane uwierzytelniające

| Zmienna | Wymagana | Opis |
| - | - | - |
| `GOLOGIN_TOKEN` | Tak (dla `open`) | Token API Gologin |
| `GOLOGIN_PROFILE_ID` | Opcjonalnie | Domyślny identyfikator profilu |
| `GOLOGIN_DAEMON_PORT` | Opcjonalnie | Port demona (domyślnie: `44777`) |
| `GOLOGIN_CONNECT_BASE` | Opcjonalnie | Punkt końcowy Cloud Browser |

### Jak uzyskać token

1. Zarejestruj się lub zaloguj na [gologin.com](https://gologin.com)
2. Otwórz **API & MCP** w panelu
3. Otwórz kartę **API**
4. Kliknij **New Token**
5. Skopiuj wygenerowany token dostępu

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

### Plik konfiguracyjny

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

***

## Architektura

Narzędzie składa się z dwóch części:

1. **CLI `gologin-agent-browser`** — przetwarza polecenia, automatycznie uruchamia demona i wypisuje zwięzłe dane wyjściowe
2. **Trwały lokalny demon** — zarządza aktywnymi sesjami przeglądarki, łączy się z Gologin Cloud Browser przez Playwright `connectOverCDP`, przechowuje aktywną stronę w pamięci, tworzy migawki, rozwiązuje referencje i śledzi metadane sesji

Transport jest wyłącznie lokalny:

* Gniazdo Unix pod adresem `${TMPDIR:-/tmp}/gologin-agent-browser.sock`
* Lokalny HTTP pod adresem `127.0.0.1:${GOLOGIN_DAEMON_PORT:-44777}`

Jeśli nie podasz identyfikatora profilu, demon utworzy tymczasowy profil chmurowy Gologin za pośrednictwem API.

***

## Jak działają referencje

`snapshot` wypisuje zwięzły widok strony i przypisuje elementom interaktywnym referencje, takie jak `@e1`, `@e2`, `@e3`. Możesz się do nich odwoływać bezpośrednio:

```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"
```

Referencje działają na zasadzie „best effort” i należy je wygenerować ponownie po nawigacji lub większych zmianach w DOM. Na stronach dynamicznych lepszym rozwiązaniem zapasowym niż nieaktualne referencje jest zazwyczaj `find`.

***

## Szybki start

```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
```

***

## Przykład pętli agenta

Typowa pętla agenta AI:

```
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
```

***

## Pełna lista poleceń

### Diagnostyka

| Polecenie | Opis |
| - | - |
| `doctor` | Sprawdza stan demona i łączność |

### Zarządzanie sesjami

| Polecenie | Opis |
| - | - |
| `open <url>` | Otwiera adres URL w sesji przeglądarki w chmurze |
| `close` | Zamyka bieżącą sesję |
| `sessions` | Wyświetla listę aktywnych sesji |
| `current` | Pokazuje informacje o bieżącej sesji |

### Odczyt strony

| Polecenie | Opis |
| - | - |
| `snapshot` | Zwięzła tekstowa migawka z referencjami elementów |
| `screenshot <path>` | Zapisuje zrzut ekranu strony |
| `pdf <path>` | Zapisuje stronę jako PDF |
| `get <kind> [target]` | Pobiera właściwości strony |

### Interakcja

| Polecenie | Opis |
| - | - |
| `click <ref>` | Klika element |
| `dblclick <ref>` | Podwójne kliknięcie |
| `type <ref> <text>` | Wpisuje tekst (dopisuje) |
| `fill <ref> <text>` | Wypełnia pole (zastępuje zawartość) |
| `hover <ref>` | Najeżdża kursorem na element |
| `select <ref> <value>` | Wybiera wartość z listy rozwijanej |
| `check <ref>` / `uncheck <ref>` | Zaznacza lub odznacza pole wyboru |
| `focus <ref>` | Ustawia fokus na elemencie |
| `find ...` | Semantyczne wyszukiwanie elementów |

### Klawiatura i przewijanie

| Polecenie | Opis |
| - | - |
| `press <key> [target]` | Naciska klawisz na klawiaturze |
| `scroll <direction> [pixels]` | Przewija stronę |
| `scrollintoview <ref>` | Przewija do elementu, aby był widoczny |

### Nawigacja

| Polecenie | Opis |
| - | - |
| `back` | Przechodzi wstecz |
| `forward` | Przechodzi do przodu |
| `reload` | Odświeża stronę |
| `wait <target\|ms>` | Czeka na element lub upłynięcie limitu czasu |

### Karty

| Polecenie | Opis |
| - | - |
| `tabs` | Wyświetla listę otwartych kart |
| `tabopen [url]` | Otwiera nową kartę |
| `tabfocus <index>` | Przełącza na wybraną kartę |
| `tabclose [index]` | Zamyka kartę |

### Pliki cookie i pamięć

| Polecenie | Opis |
| - | - |
| `cookies` | Eksportuje pliki cookie |
| `cookies-import <file>` | Importuje pliki cookie |
| `cookies-clear` | Czyści pliki cookie |
| `storage-export [path]` | Eksportuje localStorage |
| `storage-import <file>` | Importuje localStorage |
| `storage-clear` | Czyści localStorage |

### Zaawansowane

| Polecenie | Opis |
| - | - |
| `eval <expression>` | Wykonuje kod JavaScript na stronie |
| `upload <ref> <file...>` | Przesyła pliki |

### Aliasy

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

***

## Przypadki użycia i przykłady

### Sprawdzanie, czy Twoja strona przechodzi testy anti-detect

```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
```

### Logowanie do aplikacji webowej i pobieranie danych z panelu

```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
```

### Wypełnianie wieloetapowego formularza

```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
```

### Wykonywanie zrzutów ekranu stron konkurencji

```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
```

### Wyszukiwanie na stronie, która blokuje scraping

Niektóre strony wymagają wykonania JavaScriptu, zalogowania się lub interakcji, zanim pokażą wyniki. Użyj przeglądarki, aby wyszukać:

```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
```

### Zapisywanie i przywracanie stanu sesji

Wyeksportuj pliki cookie i pamięć, aby użyć ich ponownie w kolejnych sesjach:

```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
```

***

## Sesje równoległe

Używaj jawnych identyfikatorów `--session` dla niezależnych zadań w chmurze. Porządki robisz za pomocą `close --all` lub `sessions --prune --older-than-ms`.

***

## Zasady dotyczące proxy

* Profile wstępnie skonfigurowane: proxy jest ustawione w profilu w panelu Gologin lub przez API
* Profile tymczasowe: obsługują brak proxy lub niestandardowy host/port proxy
* `--proxy-country` jest dostępne wyłącznie dla profili wstępnie skonfigurowanych

***

## Powiązane materiały

* [Gologin Web Access CLI](https://gologin.com/docs/pl/cli-tools/web-access.md) — jedno narzędzie CLI (scraping + przeglądarka)
* [Local Agent Browser CLI](https://gologin.com/docs/pl/cli-tools/local-agent-browser.md) — lokalna alternatywa oparta na Orbita
* [Cloud Browser Getting Started](https://gologin.com/docs/pl/api-reference/cloud-browser/getting-started.md) — przykłady dla Puppeteer/Playwright
* [AI Skills](https://gologin.com/docs/pl/api-reference/ai-integrations/ai-skills.md) — gotowe do użycia umiejętności dla Claude Code

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

> **[Kod źródłowy](https://github.com/GologinLabs/agent-browser)**
>
> GologinLabs/agent-browser


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