gologin-agent-browser-cli 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 GoLogin
+Copyright (c) 2026 Gologin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
-# GoLogin Agent CLI
+# Gologin Agent Browser CLI
 
-GoLogin Agent CLI is a cloud browser automation CLI built for AI agents. It turns GoLogin Cloud Browser into a persistent, scriptable runtime with compact page snapshots, ref-based interaction, session memory, and shell-friendly commands.
+Gologin Agent Browser CLI is a cloud browser automation CLI built for AI agents. It turns Gologin Cloud Browser into a persistent, scriptable runtime with compact page snapshots, ref-based interaction, session memory, and shell-friendly commands.
 
 It is designed for agent loops that need to stay simple:
 
@@ -10,7 +10,7 @@ It is designed for agent loops that need to stay simple:
 - keep working across multiple CLI calls through a local daemon
 - save artifacts such as screenshots and PDFs when needed
 
-Unlike local-browser automation tools, it runs on top of a cloud browser stack built around GoLogin profiles, proxies, fingerprinting, and anti-detect capabilities.
+Unlike local-browser automation tools, it runs on top of a cloud browser stack built around Gologin profiles, proxies, fingerprinting, and anti-detect capabilities.
 
 ## Why Cloud Browser
 
@@ -22,12 +22,12 @@ Local-browser automation is convenient, but it comes with hard limits for agent
 - local networking is limited unless you bolt on your own proxy layer
 - local sessions are harder to standardize across agents and environments
 
-GoLogin Agent CLI takes the opposite approach:
+Gologin Agent Browser CLI takes the opposite approach:
 
 - cloud browser runtime instead of a local browser process
-- GoLogin profiles as the session identity layer
+- Gologin profiles as the session identity layer
 - proxy-aware browser sessions
-- fingerprint and anti-detect capabilities inherited from GoLogin
+- fingerprint and anti-detect capabilities inherited from Gologin
 - a persistent daemon that keeps agent sessions alive across CLI calls
 
 ## Architecture
@@ -37,9 +37,9 @@ The system has two parts:
 - `gologin-agent-browser` CLI
 - a persistent local daemon
 
-The CLI parses commands, auto-starts the daemon when needed, and prints compact output for agents. The daemon owns live browser sessions, connects to GoLogin Cloud Browser through Playwright `connectOverCDP`, keeps the active page in memory, builds snapshots, resolves refs like `@e1`, and tracks session metadata such as proxy mode, idle timeout, and generated artifacts.
+The CLI parses commands, auto-starts the daemon when needed, and prints compact output for agents. The daemon owns live browser sessions, connects to Gologin Cloud Browser through Playwright `connectOverCDP`, keeps the active page in memory, builds snapshots, resolves refs like `@e1`, and tracks session metadata such as proxy mode, idle timeout, and generated artifacts.
 
-If you do not provide a profile id, the daemon creates a temporary GoLogin cloud profile through the GoLogin API, uses it to open the session, and attempts to delete it when the session is closed.
+If you do not provide a profile id, the daemon creates a temporary Gologin cloud profile through the Gologin API, uses it to open the session, and attempts to delete it when the session is closed.
 
 Transport is local only:
 
@@ -77,6 +77,28 @@ npm install
 npm run build
 ```
 
+## Get a Gologin Token
+
+You need a Gologin account with API access before you can open cloud browser sessions.
+
+1. Sign up or log in at [Gologin](https://gologin.com/).
+2. In the Gologin dashboard, open `API & MCP`.
+3. Open the `API` tab.
+4. Click `New Token`.
+5. Copy the generated access token.
+
+Then export it in your shell:
+
+```bash
+export GOLOGIN_TOKEN='your_gologin_token'
+```
+
+API access depends on your Gologin account and plan. If token creation is unavailable in the dashboard, check your account access before troubleshooting the CLI.
+
+Note: the local daemon reads environment variables and config on startup. If you change `GOLOGIN_TOKEN` or `~/.gologin-agent-browser/config.json`, restart the daemon before running `open` again.
+
+If you prefer a local config file instead of an environment variable, save the same token to `~/.gologin-agent-browser/config.json`.
+
 ## Required Environment
 
 - `GOLOGIN_TOKEN` required for `open`
@@ -100,28 +122,39 @@ Save it as `~/.gologin-agent-browser/config.json`.
 ## Quickstart
 
 ```bash
-export GOLOGIN_TOKEN=your_token
+export GOLOGIN_TOKEN='your_gologin_token'
 
 gologin-agent-browser open https://example.com
 gologin-agent-browser snapshot -i
-gologin-agent-browser current
 gologin-agent-browser click @e3
-gologin-agent-browser fill "input[name='email']" "test@example.com"
-gologin-agent-browser scroll down 600
-gologin-agent-browser get title
-gologin-agent-browser pdf page.pdf
-gologin-agent-browser screenshot page.png --annotate
-gologin-agent-browser sessions
 gologin-agent-browser close
 ```
 
-More examples:
+## How Refs Work
+
+`gologin-agent-browser snapshot` prints a compact page view and assigns refs like `@e1`, `@e2`, and `@e3`.
+
+Example:
+
+```text
+- link "More information..." [ref=@e3]
+```
+
+You can then act on that element with commands like:
+
+```bash
+gologin-agent-browser click @e3
+```
+
+Refs are best-effort and should be regenerated after navigation or major DOM changes.
+
+## More Examples
 
 ```bash
 gologin-agent-browser open https://example.com --proxy-host 1.2.3.4 --proxy-port 8080 --proxy-mode http --idle-timeout-ms 300000
 gologin-agent-browser open https://example.com --profile your-preconfigured-gologin-profile
 gologin-agent-browser click "a[href*='iana']"
-gologin-agent-browser type @e4 "hello world"
+gologin-agent-browser type "textarea[name='message']" "hello world"
 gologin-agent-browser focus "input[name='email']"
 gologin-agent-browser press Enter
 gologin-agent-browser select "select[name='plan']" pro
@@ -177,7 +210,7 @@ Agents can then use those refs:
 
 ```bash
 gologin-agent-browser click @e3
-gologin-agent-browser type @e4 "hello world"
+gologin-agent-browser check @e4
 gologin-agent-browser fill "input[name='email']" "test@example.com"
 gologin-agent-browser find role button click --name "Submit"
 gologin-agent-browser screenshot page.png --annotate
@@ -203,18 +236,27 @@ Supported aliases:
 ## Current Scope
 
 - Session persistence lasts as long as the local daemon is running. Restarting the daemon clears in-memory sessions and refs.
-- Idle timeout is a local daemon policy. It does not change GoLogin account-level cloud limits.
+- Idle timeout is a local daemon policy. It does not change Gologin account-level cloud limits.
 - Snapshot and ref resolution are best-effort. Dynamic pages can invalidate refs after heavy DOM changes or navigation.
 - Snapshot output is compact and accessibility-informed, but it is not a full accessibility tree dump.
 - Annotated screenshots are based on the current snapshot/ref model, so labels are also best-effort on highly dynamic pages.
 - The daemon keeps only the latest snapshot ref map for each session.
-- Real browser sessions require a valid GoLogin Cloud Browser account and token. A profile id is optional.
-- Token-only mode works by provisioning a temporary cloud profile through the GoLogin API before connecting to Cloud Browser.
-- Proxy support is cloud-profile based. Temporary profiles can be created with a custom proxy definition, and existing GoLogin profiles can be reused with `--profile` if they already have a managed proxy attached.
-- Local Orbita is intentionally out of scope. This project targets GoLogin Cloud Browser only.
-- GoLogin cloud live-view URLs are not auto-fetched by default because the current endpoint can interfere with an active CDP session.
-- Playwright is the automation layer on top of GoLogin Cloud Browser. The browser runtime itself does not expose built-in agent actions such as `click()` or `type()`.
+- Real browser sessions require a valid Gologin Cloud Browser account and token. A profile id is optional.
+- Token-only mode works by provisioning a temporary cloud profile through the Gologin API before connecting to Cloud Browser.
+- Proxy support is cloud-profile based. Temporary profiles can be created with a custom proxy definition, and existing Gologin profiles can be reused with `--profile` if they already have a managed proxy attached.
+- Local Orbita is intentionally out of scope. This project targets Gologin Cloud Browser only.
+- Gologin cloud live-view URLs are not auto-fetched by default because the current endpoint can interfere with an active CDP session.
+- Playwright is the automation layer on top of Gologin Cloud Browser. The browser runtime itself does not expose built-in agent actions such as `click()` or `type()`.
+
+## Test Coverage
 
-## Live Smoke Check
+The repository includes unit tests for config loading, snapshot formatting, arg parsing, and URL construction.
 
-The project includes a smoke test path that only runs when `GOLOGIN_TOKEN` is present in the environment. If `GOLOGIN_PROFILE_ID` is also set, the smoke flow can reuse that profile; otherwise GoLogin can create a temporary session profile automatically. Secrets are never written into source files, tests, or examples.
+A full live browser smoke test is not shipped yet. If you want one, run a manual check with:
+
+```bash
+export GOLOGIN_TOKEN='your_gologin_token'
+gologin-agent-browser open https://example.com
+gologin-agent-browser snapshot -i
+gologin-agent-browser close
+```

package/dist/cli.js

@@ -36,7 +36,7 @@ const errors_1 = require("./lib/errors");
 const utils_1 = require("./lib/utils");
 function printUsage() {
     process.stderr.write([
-        "GoLogin Agent CLI",
+        "Gologin Agent CLI",
         "",
         "Usage:",
         "  gologin-agent-browser <command> [args] [options]",

package/dist/daemon/browser.js

@@ -155,12 +155,12 @@ async function createQuickProfile(token, sessionId) {
         })
     });
     if (!response.ok) {
-        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create GoLogin profile: ${response.status}`, 502);
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create Gologin profile: ${response.status}`, 502);
     }
     const payload = (await response.json());
     const profileId = extractProfileId(payload);
     if (!profileId) {
-        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "GoLogin profile creation returned no profile id", 502);
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "Gologin profile creation returned no profile id", 502);
     }
     return profileId;
 }
@@ -179,12 +179,12 @@ async function createManagedProfile(token, sessionId, proxy) {
         body: JSON.stringify(buildCloudProfileBody(sessionId, proxy))
     });
     if (!response.ok) {
-        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create GoLogin cloud profile: ${response.status}`, 502);
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create Gologin cloud profile: ${response.status}`, 502);
     }
     const payload = (await response.json());
     const profileId = extractProfileId(payload);
     if (!profileId) {
-        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "GoLogin profile creation returned no profile id", 502);
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "Gologin profile creation returned no profile id", 502);
     }
     let proxySummary;
     if (payload && typeof payload === "object") {
@@ -203,7 +203,7 @@ async function deleteProfile(token, profileId) {
         }
     });
     if (!response.ok) {
-        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to delete GoLogin profile ${profileId}`, 502, {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to delete Gologin profile ${profileId}`, 502, {
             profileId
         });
     }

package/dist/daemon/server.js

@@ -227,7 +227,7 @@ process.on("SIGTERM", () => {
 });
 startServers()
     .then(() => {
-    logInfo("GoLogin Agent daemon started");
+    logInfo("Gologin Agent daemon started");
 })
     .catch((error) => {
     logError("Failed to start daemon", error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gologin-agent-browser-cli",
-  "version": "0.1.0",
-  "description": "Agent-native cloud browser automation CLI for GoLogin",
+  "version": "0.1.2",
+  "description": "Agent-native cloud browser automation CLI for Gologin",
   "main": "dist/cli.js",
   "types": "dist/lib/types.d.ts",
   "files": [
@@ -43,7 +43,7 @@
     "playwright",
     "browser"
   ],
-  "author": "GoLogin",
+  "author": "Gologin",
   "license": "MIT",
   "engines": {
     "node": ">=18"