chrome-pool-cli

CLI for headless Chrome automation via Chrome Pool — a shared pool of headless Chrome instances with session management, load balancing, and autoscaling.

No browser dependencies needed. Connect to a Chrome Pool server and control Chrome from the command line.

Install

npm install -g @startanaicompany/chrome-pool-cli

Setup

export CHROME_POOL_URL=http://your-pool-server:9300
export CHROME_POOL_CLIENT_ID=my-agent  # optional, auto-generated if omitted

Quick Start

# Check pool status
chrome-pool status

# Create a session, browse, close
chrome-pool session create --name my-session
chrome-pool navigate https://example.com
chrome-pool screenshot page.png
chrome-pool snapshot          # accessibility tree (LLM-friendly)
chrome-pool eval "document.title"
chrome-pool session close

Batch Execution

Run multiple steps in a single process (3-4x faster than individual commands):

chrome-pool run --create --close --steps "
  emulate iphone-14
  navigate https://example.com
  wait-for h1
  assert title Example Domain
  screenshot homepage.png
  html h1
"

Or from a file:

chrome-pool run --create --close script.txt

Commands

Session Management

| Command | Description | |---------|-------------| | session create [--name <n>] | Create a new browser session | | session list | List your sessions (client-scoped) | | session use <id> | Switch active session (prefix match) | | session close [id] | Close session |

Navigation

| Command | Description | |---------|-------------| | navigate <url> [--timeout ms] | Navigate and wait for page load | | wait-for <selector> [--timeout] | Wait for CSS selector to appear | | wait-for-text <text> [--timeout] | Wait for text to appear on page |

Page Interaction

| Command | Description | |---------|-------------| | click <target> [-s\|-t] | Click by CSS selector or text content | | type <selector> <text> | Type into an input field | | press <key> | Press a key (Enter, Tab, Escape, arrows, etc.) | | hover <selector> | Hover over an element | | fill-form <json> [--submit] | Fill multiple fields: '{"#email":"x","#pass":"y"}' | | upload <file> <selector> | Upload file to a file input | | dialog [accept\|dismiss] | Handle browser alert/confirm/prompt |

Inspection

| Command | Description | |---------|-------------| | screenshot [file] [--full-page] | Take screenshot (PNG or --quality for JPEG) | | snapshot | Get accessibility tree (great for LLM agents) | | html [--selector <sel>] | Get page or element HTML | | eval <expression> | Evaluate JavaScript | | console [--duration] [--level] | Capture browser console messages | | network [--errors] [--body] | Capture network requests | | pdf [file] [--landscape] [--format] | Save page as PDF |

Cookies

| Command | Description | |---------|-------------| | cookies list | List all cookies | | cookies set <name> <value> | Set a cookie | | cookies clear | Clear all cookies | | cookies save <file> | Save cookies to JSON file | | cookies load <file> | Load cookies from JSON file |

Emulation & Frames

| Command | Description | |---------|-------------| | emulate <device> | Emulate device (iphone-14, pixel-7, ipad, desktop-hd) | | emulate --width --height --mobile | Custom viewport/user agent | | frames | List all frames/iframes | | select-frame <index\|id> | Switch to an iframe | | pages list\|new\|close | Manage browser tabs |

Testing & Assertions

| Command | Description | |---------|-------------| | assert selector <sel> | Exit 0 if selector exists, 1 if not | | assert text <text> | Exit 0 if text found on page | | assert title <text> | Exit 0 if page title matches | | assert url <text> | Exit 0 if URL matches | | assert no-errors | Exit 0 if no JS exceptions |

Other

| Command | Description | |---------|-------------| | clipboard read\|write | Read/write browser clipboard | | status | Show pool health and chrome instances | | --json | Global flag: JSON output on all commands | | --retries <n> | Retry on transient failures |

Run Script Reference

All commands above work inside run scripts. Additional run-only steps:

wait <ms>                  Sleep for milliseconds
log <message>              Print a message

Example: automated QA health check with assertions and exit codes:

chrome-pool run --create --close --steps "
  navigate https://my-app.com
  wait-for .dashboard
  assert title Dashboard
  assert selector .status-ok
  console --level error
  network --errors
  screenshot health-check.png
"
echo "Exit code: $?"  # 0 = all pass, 1 = assertion failed

Session Persistence

Sessions are client-scoped via CHROME_POOL_CLIENT_ID. Each client only sees its own sessions. Active session persists across commands in ~/.chrome-pool/session.

Cookie persistence for login flows:

chrome-pool cookies save ./auth-cookies.json    # after login
chrome-pool cookies load ./auth-cookies.json    # in future sessions

Requirements

• Node.js >= 18
• A running Chrome Pool server

License

MIT