Skip to main content
Gologin Agent Browser CLI turns Gologin browser profiles into a persistent, scriptable runtime for AI agents. Sessions run in Gologin Cloud Browser or in Orbita on your own machine. It provides compact page snapshots, ref-based interaction, session memory, and shell-friendly output. Unlike writing Puppeteer/Playwright code from scratch, this CLI gives agents a ready-made command surface for browser automation — no boilerplate, no session management code.

Cloud or local runtime

The CLI has two runtimes with the same commands. Both use Gologin profiles, fingerprints, and proxies, and a daemon keeps sessions alive across CLI calls. Choose the runtime per command with --runtime cloud|local|auto, or set GOLOGIN_AGENT_BROWSER_RUNTIME once:
By default (auto), profile, runbook, and job commands run locally and everything else runs in the cloud. Once you open a local session, pass --runtime local to the commands that follow too. See Local runtime for requirements and local-only commands.

Install

Or run without global install:
Requires Node.js >= 18. The local runtime needs Node.js 20 or later.

Credentials

Get a token

  1. Sign up or log in at gologin.com
  2. Open API & MCP in the dashboard
  3. Open the API tab
  4. Click New Token
  5. Copy the generated access token

Config file

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

Architecture

Two parts:
  1. gologin-agent-browser CLI — parses commands, picks the runtime, auto-starts the matching daemon, prints compact output
  2. Persistent local daemons, one per runtime — own live browser sessions, connect to Gologin Cloud Browser or local Orbita through Playwright connectOverCDP, keep the active page in memory, build snapshots, resolve refs, track session metadata
Transport is local only. The cloud daemon listens on:
  • Unix socket at ${TMPDIR:-/tmp}/gologin-agent-browser.sock
  • Localhost HTTP on 127.0.0.1:${GOLOGIN_DAEMON_PORT:-44777}
In the cloud runtime, if you do not provide a profile ID, the daemon creates a temporary Gologin cloud profile through the API.

How refs work

snapshot prints a compact page view and assigns refs like @e1, @e2, @e3 to interactive elements. You act on them directly:
Refs are best-effort and should be regenerated after navigation or major DOM changes. Commands also accept CSS selectors instead of refs. On dynamic pages, find is usually a better fallback than stale refs: it locates the element on the live page and acts on it in one step.

Quick start


Agent loop example

A typical AI agent loop:

Full command reference

Diagnostics

Session management

Page reading

Interaction

Keyboard and scroll

Tabs

Cookies and storage

Advanced

Profiles, proxies, and the Gologin API

These commands call the Gologin API with your token and don’t need the browser daemon.
Add --help to any command to print its usage.

Local runtime only

profiles, profile, profile-create, profile-update, profile-import, profile-sync, profile-delete, run, batch, jobs, and job manage local profiles, runbooks, and job history. See Local runtime.

Aliases


Use cases and examples

Check if your site passes anti-detect tests

Log into a web app and extract dashboard data

Fill out a multi-step form

Take screenshots of competitor pages

Search on a site that blocks scraping

Some sites require JavaScript execution, login, or interaction before showing results. Use the browser to search:

Save and restore session state

Export cookies and storage to reuse across sessions:

Parallel sessions

Use explicit --session IDs for independent cloud tasks. Clean up with close --all or sessions --prune --older-than-ms.

Proxy rules

  • Preconfigured profiles: proxy is set on the profile via Gologin dashboard or API, for example proxy add-gologin <profileId> --country us
  • Temporary cloud profiles: no proxy, or your own proxy with --proxy-host and --proxy-port (plus --proxy-mode http|socks4|socks5, --proxy-user, --proxy-pass)
  • In the cloud runtime, open doesn’t accept --proxy-country. For Gologin proxy traffic from a country, add a Gologin proxy to a profile and open it with --profile
  • In the local runtime, open, profile-create, and profile-update accept --proxy-country

npm package

gologin-agent-browser-cli

Source code

GologinLabs/agent-browser