gologin-agent-browser-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# Gologin Agent Browser CLI
+
+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:
+
+- open a live browser session
+- read the page as a compact text snapshot
+- act on stable refs like `@e3`
+- keep working across multiple CLI calls through a local daemon
+- save artifacts such as screenshots and PDFs when needed
+- inspect daemon health with `doctor`
+- manage tabs, cookies, storage, and in-page eval without dropping to raw Playwright
+
+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
+
+Local-browser automation is convenient, but it comes with hard limits for agent workflows that need to survive real-world websites:
+
+- local browsers are easier to detect
+- local runs usually do not carry profile-based fingerprinting
+- local runs do not come with persistent cloud browser profiles
+- local networking is limited unless you bolt on your own proxy layer
+- local sessions are harder to standardize across agents and environments
+
+Gologin Agent Browser CLI takes the opposite approach:
+
+- cloud browser runtime instead of a local browser process
+- Gologin profiles as the session identity layer
+- proxy-aware browser sessions
+- fingerprint and anti-detect capabilities inherited from Gologin
+- a persistent daemon that keeps agent sessions alive across CLI calls
+
+## Architecture
+
+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.
+
+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:
+
+- Unix socket at `${TMPDIR:-/tmp}/gologin-agent-browser.sock` on Unix-like systems
+- localhost HTTP on `127.0.0.1:${GOLOGIN_DAEMON_PORT:-44777}`
+
+## Installation
+
+Node.js 18+ is required.
+
+Install from npm:
+
+```bash
+npm install -g gologin-agent-browser-cli
+```
+
+Run it directly:
+
+```bash
+gologin-agent-browser --help
+```
+
+Or use it without a global install:
+
+```bash
+npx gologin-agent-browser-cli --help
+```
+
+Developer setup from source:
+
+```bash
+git clone https://github.com/GologinLabs/agent-browser.git
+cd agent-browser
+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`
+- `GOLOGIN_PROFILE_ID` optional default profile for `open`
+- `GOLOGIN_DAEMON_PORT` optional, defaults to `44777`
+- `GOLOGIN_CONNECT_BASE` optional, defaults to `https://cloudbrowser.gologin.com/connect`
+
+Optional config file:
+
+```json
+{
+  "token": "from-your-own-secret-store",
+  "defaultProfileId": "profile-id",
+  "daemonPort": 44777,
+  "connectBase": "https://cloudbrowser.gologin.com/connect"
+}
+```
+
+Save it as `~/.gologin-agent-browser/config.json`.
+
+## Quickstart
+
+```bash
+export GOLOGIN_TOKEN='your_gologin_token'
+
+gologin-agent-browser open https://example.com
+gologin-agent-browser snapshot -i
+gologin-agent-browser click @e3
+gologin-agent-browser close
+```
+
+## 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.
+
+Most mutating commands will leave the page in `snapshot=stale` state. When that happens, run `snapshot` again before using old refs.
+
+On dynamic pages, `find ...` is usually a better fallback than stale refs because it re-resolves against the live page instead of the last snapshot.
+
+## 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 tabs
+gologin-agent-browser tabopen https://www.iana.org
+gologin-agent-browser tabfocus 2
+gologin-agent-browser tabclose 2
+gologin-agent-browser click "a[href*='iana']"
+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
+gologin-agent-browser check "input[name='terms']"
+gologin-agent-browser uncheck "input[name='newsletter']"
+gologin-agent-browser scrollintoview "#submit"
+gologin-agent-browser find label "Email" fill "test@example.com"
+gologin-agent-browser upload "input[type='file']" /absolute/path/to/avatar.png
+gologin-agent-browser wait --text "Welcome"
+gologin-agent-browser cookies --json
+gologin-agent-browser storage-export /tmp/storage.json
+gologin-agent-browser eval "document.title" --json
+gologin-agent-browser back
+gologin-agent-browser forward
+gologin-agent-browser reload
+gologin-agent-browser screenshot page.png --annotate --press-escape
+```
+
+## Commands
+
+- `doctor [--json]`
+- `open <url> [--profile <profileId>] [--session <sessionId>] [--idle-timeout-ms <ms>]`
+- `open <url> [--proxy-host <host> --proxy-port <port> --proxy-mode <http|socks4|socks5> --proxy-user <user> --proxy-pass <pass>]`
+- `tabs [--session <sessionId>]`
+- `tabopen [url] [--session <sessionId>]`
+- `tabfocus <index> [--session <sessionId>]`
+- `tabclose [index] [--session <sessionId>]`
+- `cookies [--session <sessionId>] [--output <path>] [--json]`
+- `cookies-import <cookies.json> [--session <sessionId>]`
+- `cookies-clear [--session <sessionId>]`
+- `storage-export [path] [--scope <local|session|both>] [--session <sessionId>] [--json]`
+- `storage-import <storage.json> [--scope <local|session|both>] [--clear] [--session <sessionId>]`
+- `storage-clear [--scope <local|session|both>] [--session <sessionId>]`
+- `eval <expression> [--json] [--session <sessionId>]`
+- `snapshot [--session <sessionId>] [--interactive]`
+- `click <target> [--session <sessionId>]`
+- `dblclick <target> [--session <sessionId>]`
+- `focus <target> [--session <sessionId>]`
+- `type <target> <text> [--session <sessionId>]`
+- `fill <target> <text> [--session <sessionId>]`
+- `hover <target> [--session <sessionId>]`
+- `select <target> <value> [--session <sessionId>]`
+- `check <target> [--session <sessionId>]`
+- `uncheck <target> [--session <sessionId>]`
+- `press <key> [target] [--session <sessionId>]`
+- `scroll <up|down|left|right> [pixels] [--target <target>] [--session <sessionId>]`
+- `scrollintoview <target> [--session <sessionId>]`
+- `wait <target|ms> [--text <text>] [--url <pattern>] [--load <state>] [--session <sessionId>]`
+- `get <text|value|html|title|url> [target] [--session <sessionId>]`
+- `back [--session <sessionId>]`
+- `forward [--session <sessionId>]`
+- `reload [--session <sessionId>]`
+- `find <role|text|label|placeholder|first|last|nth> ...`
+- `upload <target> <file...> [--session <sessionId>]`
+- `pdf <path> [--session <sessionId>]`
+- `screenshot <path> [--annotate] [--press-escape] [--session <sessionId>]`
+- `close [--session <sessionId>]`
+- `sessions`
+- `current`
+
+## Help And Diagnostics
+
+Subcommand help now works without a daemon round-trip:
+
+```bash
+gologin-agent-browser open --help
+gologin-agent-browser screenshot --help
+```
+
+When bootstrap is flaky, inspect the local setup directly:
+
+```bash
+gologin-agent-browser doctor
+gologin-agent-browser doctor --json
+```
+
+`doctor` reports whether a token is configured, which connect base is configured, which local transports are reachable, and where the daemon log is written.
+
+## Example Session Flow
+
+`snapshot` produces compact output designed for agent consumption:
+
+```text
+session=s1 url=https://example.com/
+- heading "Example Domain" [ref=@e1]
+- paragraph "This domain is for use in illustrative examples in documents." [ref=@e2]
+- link "More information..." [ref=@e3]
+- checkbox "Accept terms" [checked] [ref=@e4]
+- select "Plan" [selected=Pro] [ref=@e5]
+```
+
+Agents can then use those refs:
+
+```bash
+gologin-agent-browser click @e3
+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
+```
+
+Targets can be either snapshot refs like `@e4` or raw Playwright/CSS selectors. `find` adds semantic locator flows similar to agent-browser.
+
+If a ref stops resolving after navigation or a DOM update, prefer a fresh `snapshot` or use a semantic `find ...` command instead.
+
+`open`, `current`, and `sessions` also expose session metadata in a shell-friendly form:
+
+```text
+session=s1 url=https://example.com snapshot=fresh proxy=http:1.2.3.4:8080 idleTimeoutMs=300000 shot=/tmp/page.png pdf=/tmp/page.pdf
+```
+
+When screenshots or PDFs are generated, `current` and `sessions` include the latest artifact paths as `shot=...` and `pdf=...`.
+
+Supported aliases:
+
+- `goto`, `navigate` -> `open`
+- `tabnew` -> `tabopen`
+- `tabswitch` -> `tabfocus`
+- `js` -> `eval`
+- `key` -> `press`
+- `scrollinto` -> `scrollintoview`
+- `quit`, `exit` -> `close`
+
+## 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.
+- 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.
+- `screenshot` has a hard timeout and supports `--press-escape` for pages with modals, chat widgets, or overlay-driven render issues.
+- 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()`.
+
+## Test Coverage
+
+The repository includes unit tests for config loading, snapshot formatting, arg parsing, and URL construction.
+
+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.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function isHelpRequest(argv: string[]): boolean;
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHelpRequest = isHelpRequest;
+exports.main = main;
+const back_1 = require("./commands/back");
+const check_1 = require("./commands/check");
+const click_1 = require("./commands/click");
+const close_1 = require("./commands/close");
+const cookies_1 = require("./commands/cookies");
+const cookiesClear_1 = require("./commands/cookiesClear");
+const cookiesImport_1 = require("./commands/cookiesImport");
+const current_1 = require("./commands/current");
+const doctor_1 = require("./commands/doctor");
+const dblclick_1 = require("./commands/dblclick");
+const eval_1 = require("./commands/eval");
+const fill_1 = require("./commands/fill");
+const find_1 = require("./commands/find");
+const focus_1 = require("./commands/focus");
+const forward_1 = require("./commands/forward");
+const get_1 = require("./commands/get");
+const hover_1 = require("./commands/hover");
+const open_1 = require("./commands/open");
+const pdf_1 = require("./commands/pdf");
+const press_1 = require("./commands/press");
+const reload_1 = require("./commands/reload");
+const screenshot_1 = require("./commands/screenshot");
+const scroll_1 = require("./commands/scroll");
+const scrollIntoView_1 = require("./commands/scrollIntoView");
+const storageClear_1 = require("./commands/storageClear");
+const storageExport_1 = require("./commands/storageExport");
+const storageImport_1 = require("./commands/storageImport");
+const sessions_1 = require("./commands/sessions");
+const snapshot_1 = require("./commands/snapshot");
+const select_1 = require("./commands/select");
+const tabClose_1 = require("./commands/tabClose");
+const tabFocus_1 = require("./commands/tabFocus");
+const tabOpen_1 = require("./commands/tabOpen");
+const tabs_1 = require("./commands/tabs");
+const type_1 = require("./commands/type");
+const uncheck_1 = require("./commands/uncheck");
+const upload_1 = require("./commands/upload");
+const wait_1 = require("./commands/wait");
+const daemon_1 = require("./lib/daemon");
+const config_1 = require("./lib/config");
+const errors_1 = require("./lib/errors");
+const commandUsage = {
+    open: "open <url> [--profile <profileId>] [--session <sessionId>] [--idle-timeout-ms <ms>] [--proxy-host <host> --proxy-port <port> --proxy-mode <http|socks4|socks5>] (aliases: goto, navigate)",
+    doctor: "doctor [--json]",
+    tabs: "tabs [--session <sessionId>]",
+    tabopen: "tabopen [url] [--session <sessionId>] (alias: tabnew)",
+    tabfocus: "tabfocus <index> [--session <sessionId>] (alias: tabswitch)",
+    tabclose: "tabclose [index] [--session <sessionId>]",
+    cookies: "cookies [--session <sessionId>] [--output <path>] [--json]",
+    "cookies-import": "cookies-import <cookies.json> [--session <sessionId>]",
+    "cookies-clear": "cookies-clear [--session <sessionId>]",
+    "storage-export": "storage-export [path] [--scope <local|session|both>] [--session <sessionId>] [--json]",
+    "storage-import": "storage-import <storage.json> [--scope <local|session|both>] [--clear] [--session <sessionId>]",
+    "storage-clear": "storage-clear [--scope <local|session|both>] [--session <sessionId>]",
+    eval: "eval <expression> [--json] [--session <sessionId>] (alias: js)",
+    snapshot: "snapshot [--session <sessionId>] [--interactive|-i]",
+    click: "click <target> [--session <sessionId>]",
+    dblclick: "dblclick <target> [--session <sessionId>]",
+    focus: "focus <target> [--session <sessionId>]",
+    type: "type <target> <text> [--session <sessionId>]",
+    fill: "fill <target> <text> [--session <sessionId>]",
+    hover: "hover <target> [--session <sessionId>]",
+    select: "select <target> <value> [--session <sessionId>]",
+    check: "check <target> [--session <sessionId>]",
+    uncheck: "uncheck <target> [--session <sessionId>]",
+    press: "press <key> [target] [--session <sessionId>] (alias: key)",
+    scroll: "scroll <up|down|left|right> [pixels] [--target <target>] [--session <sessionId>]",
+    scrollintoview: "scrollintoview <target> [--session <sessionId>] (alias: scrollinto)",
+    wait: "wait <target|ms> [--text <text>] [--url <pattern>] [--load <state>] [--session <sessionId>]",
+    get: "get <text|value|html|title|url> [target] [--session <sessionId>]",
+    back: "back [--session <sessionId>]",
+    forward: "forward [--session <sessionId>]",
+    reload: "reload [--session <sessionId>]",
+    find: "find <role|text|label|placeholder|first|last|nth> ... [--exact]",
+    upload: "upload <target> <file...> [--session <sessionId>]",
+    pdf: "pdf <path> [--session <sessionId>]",
+    screenshot: "screenshot <path> [--annotate] [--press-escape] [--session <sessionId>]",
+    close: "close [--session <sessionId>] (aliases: quit, exit)",
+    sessions: "sessions",
+    current: "current"
+};
+function printUsage() {
+    process.stderr.write([
+        "Gologin Agent CLI",
+        "",
+        "Usage:",
+        "  gologin-agent-browser <command> [args] [options]",
+        "",
+        "Commands:",
+        ...Object.values(commandUsage).map((usage) => `  ${usage}`),
+        "",
+        "Environment:",
+        "  GOLOGIN_TOKEN",
+        "  GOLOGIN_PROFILE_ID",
+        "  GOLOGIN_DAEMON_PORT",
+        "  GOLOGIN_CONNECT_BASE"
+    ].join("\n") + "\n");
+}
+function printCommandUsage(command) {
+    process.stderr.write([
+        "Usage:",
+        `  gologin-agent-browser ${commandUsage[command]}`,
+        "",
+        "Tip:",
+        "  Use --json when you want machine-readable output."
+    ].join("\n") + "\n");
+}
+function commandRequiresDaemon(command) {
+    return command !== "doctor";
+}
+function isHelpRequest(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
+async function runCommand(command, context, args) {
+    switch (command) {
+        case "open":
+            await (0, open_1.runOpenCommand)(context, args);
+            return;
+        case "doctor":
+            await (0, doctor_1.runDoctorCommand)(context, args);
+            return;
+        case "tabs":
+            await (0, tabs_1.runTabsCommand)(context, args);
+            return;
+        case "tabopen":
+            await (0, tabOpen_1.runTabOpenCommand)(context, args);
+            return;
+        case "tabfocus":
+            await (0, tabFocus_1.runTabFocusCommand)(context, args);
+            return;
+        case "tabclose":
+            await (0, tabClose_1.runTabCloseCommand)(context, args);
+            return;
+        case "cookies":
+            await (0, cookies_1.runCookiesCommand)(context, args);
+            return;
+        case "cookies-import":
+            await (0, cookiesImport_1.runCookiesImportCommand)(context, args);
+            return;
+        case "cookies-clear":
+            await (0, cookiesClear_1.runCookiesClearCommand)(context, args);
+            return;
+        case "storage-export":
+            await (0, storageExport_1.runStorageExportCommand)(context, args);
+            return;
+        case "storage-import":
+            await (0, storageImport_1.runStorageImportCommand)(context, args);
+            return;
+        case "storage-clear":
+            await (0, storageClear_1.runStorageClearCommand)(context, args);
+            return;
+        case "eval":
+            await (0, eval_1.runEvalCommand)(context, args);
+            return;
+        case "snapshot":
+            await (0, snapshot_1.runSnapshotCommand)(context, args);
+            return;
+        case "click":
+            await (0, click_1.runClickCommand)(context, args);
+            return;
+        case "dblclick":
+            await (0, dblclick_1.runDoubleClickCommand)(context, args);
+            return;
+        case "focus":
+            await (0, focus_1.runFocusCommand)(context, args);
+            return;
+        case "type":
+            await (0, type_1.runTypeCommand)(context, args);
+            return;
+        case "fill":
+            await (0, fill_1.runFillCommand)(context, args);
+            return;
+        case "hover":
+            await (0, hover_1.runHoverCommand)(context, args);
+            return;
+        case "select":
+            await (0, select_1.runSelectCommand)(context, args);
+            return;
+        case "check":
+            await (0, check_1.runCheckCommand)(context, args);
+            return;
+        case "uncheck":
+            await (0, uncheck_1.runUncheckCommand)(context, args);
+            return;
+        case "press":
+            await (0, press_1.runPressCommand)(context, args);
+            return;
+        case "scroll":
+            await (0, scroll_1.runScrollCommand)(context, args);
+            return;
+        case "scrollintoview":
+            await (0, scrollIntoView_1.runScrollIntoViewCommand)(context, args);
+            return;
+        case "wait":
+            await (0, wait_1.runWaitCommand)(context, args);
+            return;
+        case "get":
+            await (0, get_1.runGetCommand)(context, args);
+            return;
+        case "back":
+            await (0, back_1.runBackCommand)(context, args);
+            return;
+        case "forward":
+            await (0, forward_1.runForwardCommand)(context, args);
+            return;
+        case "reload":
+            await (0, reload_1.runReloadCommand)(context, args);
+            return;
+        case "find":
+            await (0, find_1.runFindCommand)(context, args);
+            return;
+        case "upload":
+            await (0, upload_1.runUploadCommand)(context, args);
+            return;
+        case "pdf":
+            await (0, pdf_1.runPdfCommand)(context, args);
+            return;
+        case "screenshot":
+            await (0, screenshot_1.runScreenshotCommand)(context, args);
+            return;
+        case "close":
+            await (0, close_1.runCloseCommand)(context, args);
+            return;
+        case "sessions":
+            await (0, sessions_1.runSessionsCommand)(context, args);
+            return;
+        case "current":
+            await (0, current_1.runCurrentCommand)(context, args);
+            return;
+    }
+}
+function normalizeCommand(commandArg) {
+    const aliases = {
+        goto: "open",
+        navigate: "open",
+        tabnew: "tabopen",
+        tabswitch: "tabfocus",
+        js: "eval",
+        key: "press",
+        scrollinto: "scrollintoview",
+        quit: "close",
+        exit: "close"
+    };
+    if (aliases[commandArg]) {
+        return aliases[commandArg];
+    }
+    const directCommands = new Set([
+        "open",
+        "doctor",
+        "tabs",
+        "tabopen",
+        "tabfocus",
+        "tabclose",
+        "cookies",
+        "cookies-import",
+        "cookies-clear",
+        "storage-export",
+        "storage-import",
+        "storage-clear",
+        "eval",
+        "snapshot",
+        "click",
+        "dblclick",
+        "focus",
+        "type",
+        "fill",
+        "hover",
+        "select",
+        "check",
+        "uncheck",
+        "press",
+        "scroll",
+        "scrollintoview",
+        "wait",
+        "get",
+        "back",
+        "forward",
+        "reload",
+        "find",
+        "upload",
+        "pdf",
+        "screenshot",
+        "close",
+        "sessions",
+        "current"
+    ]);
+    return directCommands.has(commandArg) ? commandArg : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const commandArg = argv[0];
+    if (!commandArg || commandArg === "--help" || commandArg === "-h") {
+        printUsage();
+        process.exit(commandArg ? 0 : 1);
+    }
+    const command = normalizeCommand(commandArg);
+    if (!command) {
+        throw new errors_1.AppError("BAD_REQUEST", `Unknown command: ${commandArg}`, 400);
+    }
+    if (isHelpRequest(argv.slice(1))) {
+        printCommandUsage(command);
+        process.exit(0);
+    }
+    const config = (0, config_1.loadConfig)();
+    const client = commandRequiresDaemon(command)
+        ? await (0, daemon_1.createHealthyDaemonClient)(config)
+        : {
+            transport: {
+                kind: "http",
+                host: config.daemonHost,
+                port: config.daemonPort
+            },
+            async request() {
+                throw new errors_1.AppError("DAEMON_UNREACHABLE", "This command should not call the daemon client", 500);
+            }
+        };
+    const context = {
+        config,
+        client,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        cwd: process.cwd()
+    };
+    await runCommand(command, context, argv.slice(1));
+}
+if (require.main === module) {
+    main().catch((error) => {
+        process.stderr.write(`${(0, errors_1.formatErrorLine)(error)}\n`);
+        process.exit(error instanceof errors_1.AppError ? 1 : 1);
+    });
+}

package/dist/commands/back.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../lib/types";
+export declare function runBackCommand(context: CommandContext, argv: string[]): Promise<void>;