# How to Run the Examples in ego-lite: A Complete Step-by-Step Guide

> Learn how to run examples in ego-lite with this step-by-step guide. Install the skill, build the runtime, and pipe JavaScript to the CLI for effortless execution.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-03

---

**To run the examples in ego-lite, install the skill with `npx skills add`, build the Node-based helper runtime, and pipe JavaScript snippets into the bundled CLI via STDIN.**

The **ego-lite** repository from Citrolabs provides a lightweight browser automation framework that connects to a closed-source browser binary through the Chrome DevTools Protocol (CDP). The examples demonstrate core automation patterns—navigation, screenshots, and element interaction—using a helper runtime that exposes convenient async functions.

## Install the ego-lite Skill and Dependencies

Before running any examples, you need the skill registered in your shell and the Node dependencies installed.

### Register the Skill

The skill installer adds helper commands and configures the environment:

```bash
npx skills add citrolabs/ego-lite

```

### Install Package Dependencies

Navigate to the browser package and install dependencies:

```bash
cd package/ego-browser
npm ci

```

This installs the runtime requirements defined in [`package/ego-browser/package.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/package.json).

## Build the Helper Runtime

The examples rely on a bundled CLI that communicates with the ego-lite browser. Build it with:

```bash
npm test

```

This command:

1. Compiles the TypeScript source
2. Outputs the bundled CLI to [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js)
3. Runs unit tests that include embedded example snippets

The build process is defined in the package scripts and produces the executable entry point for all example workflows.

## Run Examples via STDIN (Heredoc Method)

The primary way to execute examples is piping JavaScript directly into the built CLI. The runtime exposes **helper functions** from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)—including `openOrReuseTab`, `screenshot`, `click`, and `getPageInfo`—that abstract CDP operations.

### Basic Example: Open a Page and Extract Title

```bash
node dist/out/index.js <<'JS'
await openOrReuseTab('https://example.com', { wait: true })
const info = await getPageInfo()
console.log('Page title:', info.title)
JS

```

### Screenshot Example

```bash
node dist/out/index.js <<'JS'
await openOrReuseTab('https://example.com', { wait: true })
await screenshot({ fullPage: true, path: 'full.png' })
JS

```

### Interaction Example

```bash
node dist/out/index.js <<'EOF'
await openOrReuseTab('https://example.com', { wait: true })
await click('text=More info')
await screenshot({ path: 'info.png' })
EOF

```

The `openOrReuseTab` function optionally accepts a `wait: true` parameter to block until the page load event fires. Screenshots support both viewport-only and `fullPage` captures.

## Run the Full End-to-End Example Suite

For comprehensive verification against a real Chromium instance, execute the e2e runner:

```bash
npm run e2e

```

This script—located at `scripts/real-browser-e2e/`—performs the following:

- Launches the bundled ego-lite binary
- Creates a temporary task workspace
- Executes example flows covering navigation, evaluation, interaction, and observation

The individual test cases reside in `scripts/real-browser-e2e/cases/*.mjs` and serve as reference implementations for common automation patterns.

## Key Source Files for Understanding Examples

| File Path | Purpose |
|-----------|---------|
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Defines the **helper context** (`openOrReuseTab`, `screenshot`, `click`, etc.) available to example scripts |
| [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) | Core CDP transport and session management |
| [`package/ego-browser/README.md`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/README.md) | Quick-start documentation and CLI usage |
| [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) | Skill definition and public API reference |
| `scripts/real-browser-e2e/cases/*.mjs` | Standalone example test cases |

## Troubleshooting Common Issues

- **CLI not found**: Ensure `npm test` completed successfully and check that [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) exists
- **Connection failures**: Verify the ego-lite browser binary is accessible in your PATH
- **Helper functions undefined**: Confirm you're piping JavaScript into the built CLI, not running raw Node

## Summary

- **Install**: `npx skills add citrolabs/ego-lite` registers the skill; `npm ci` installs dependencies
- **Build**: `npm test` produces [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) and validates examples
- **Execute**: Pipe JS snippets via heredoc to the CLI; helper functions from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) handle CDP communication
- **Verify**: `npm run e2e` runs the full example suite against a real browser instance

## Frequently Asked Questions

### What helper functions are available in ego-lite examples?

The runtime exposes **async helpers** defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts): `openOrReuseTab`, `screenshot`, `click`, `getPageInfo`, `evaluate`, `fill`, `press`, and others. These abstract CDP commands into concise, awaitable operations.

### Can I run examples without building first?

No. The CLI at [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) must exist before executing examples. The build step bundles the TypeScript source and helper context. Run `npm test` once to generate it.

### Where are the example scripts stored?

Unit test examples embed in the test suite. Full workflow examples live in `package/ego-browser/scripts/real-browser-e2e/cases/*.mjs`—individual modules demonstrating navigation, page evaluation, element interaction, and visual observation.

### How does the runtime communicate with the browser?

[`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) establishes a CDP WebSocket connection to the ego-lite browser binary, exposing a session-based transport layer that the helper functions use to send commands and receive events.