npm package: @startanaicompany/chrome-pool-cli
Description: CLI for Chrome Pool — manage sessions, navigate, screenshot, interact via CDP
Latest version: 0.3.0

# chrome-pool-cli

CLI for headless Chrome automation via [Chrome Pool](https://github.com/Ryan-SAAS/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

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

## Setup

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

## Quick Start

```bash
# 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):

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

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

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

```bash
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](https://github.com/Ryan-SAAS/chrome-pool) server

## License

MIT