# ego-lite CLI Commands: Complete Reference for the Browser Automation Tool

> Explore the complete ego-lite CLI command reference. Learn to execute JavaScript heredocs, check your environment, clear cache, and enable verbose logging with this browser automation tool.

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

---

**The ego-lite CLI provides five core commands and flags including `ego-browser nodejs` for executing JavaScript heredocs, `--help` for usage info, `--doctor` for environment checks, `--reload` for cache clearing, and `--debug-clicks` for verbose logging.**

The **ego-lite** repository from CitroLabs delivers a lightweight Node.js browser automation framework centered around the **ego-browser** package. Understanding the available CLI commands is essential for developers building automated agents that script web interactions. This guide covers every command-line option, flag, and npm script based on the actual source implementation in `citrolabs/ego-lite`.

## Core CLI Commands and Flags

The ego-lite CLI is invoked through the `ego-browser` binary, defined in [`package/ego-browser/package.json`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/package.json). The entry point lives at [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts), which parses flags, reads STDIN, injects helper utilities, and executes scripts.

### `ego-browser nodejs` — Execute JavaScript from STDIN

The primary command for agent scripting. It reads a JavaScript heredoc from standard input and runs it inside the ego-browser runtime with full access to Playwright-style helpers.

```bash
ego-browser nodejs <<'EOF'
await browser.openOrReuseTab('https://example.com', { wait: true })
console.log(await page.snapshot())
EOF

```

The helpers available to these scripts—`browser`, `page`, `taskSpaces`—are implemented in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

### `-h, --help` — Display Usage Information

Prints help text covering available options and usage examples. Run this first to confirm your installation.

```bash
ego-browser --help

```

### `--doctor` — Environment Sanity Check

Validates the host environment and reports missing dependencies before you attempt to run scripts. Useful for CI/CD pipelines and fresh installations.

```bash
ego-browser --doctor

```

### `--reload` — Force Page Reload

Discards cached snapshots and reloads the current page. Combine with script execution to ensure fresh state.

```bash
ego-browser --reload nodejs <<'EOF'
await page.click('button#submit')
EOF

```

### `--debug-clicks` — Verbose Click Logging

Enables detailed logging of mouse-click actions for debugging UI interaction failures. Often paired with `--reload` during development.

```bash
ego-browser --reload --debug-clicks <<'EOF'
await page.click('button#submit')
EOF

```

## Development npm Scripts

Beyond the CLI binary, ego-lite provides several npm scripts for repository-level development tasks. These are executed from the repository root.

| Script | Purpose |
|--------|---------|
| `npm ci` | Install exact dependencies from lockfile |
| `npm run build` | Bundle helper runtime to [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) |
| `npm test` | Build, type-check, and run Node test suite (`node --test`) |
| `npm run e2e` | Execute task-space end-to-end test suite |
| `npm run validate:site-skills` | Verify site-skill manifests are well-formed |

The `validate:site-skills` script has an alias: `validate:learnings`.

```bash

# Validate all learned site-skill manifests

npm run validate:site-skills

```

## Key Source Files and Architecture

Understanding where these commands are implemented helps when debugging or extending ego-lite:

- **[`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts)** — CLI entry point; handles flag parsing, STDIN consumption, helper injection, and script execution
- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** — Implements the public API (`page`, `browser`, `taskSpaces`) available to user scripts
- **[`README.md`](https://github.com/citrolabs/ego-lite/blob/main/README.md)** — Build/run workflow documentation and usage examples
- **[`package.json`](https://github.com/citrolabs/ego-lite/blob/main/package.json)** — Declares the `ego-browser` binary and npm script definitions

## Typical Workflow Examples

Combine flags for common development scenarios:

**Fresh start with debugging:**

```bash
ego-browser --doctor && ego-browser --reload --debug-clicks nodejs <<'EOF'
await browser.openOrReuseTab('https://app.example.com', { wait: true })
await page.click('button#login')
EOF

```

**CI validation pipeline:**

```bash
npm ci
npm run build
npm test
npm run validate:site-skills
npm run e2e

```

## Summary

- **ego-browser nodejs** is the core command for executing JavaScript heredocs against the browser runtime
- **Five CLI flags** control behavior: `--help`, `--doctor`, `--reload`, `--debug-clicks`, and the implicit script execution mode
- **npm scripts** handle build, test, validation, and e2e workflows from the repository root
- **Source files** [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts) and [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) implement the complete CLI surface

## Frequently Asked Questions

### How do I check if my ego-lite installation is working correctly?

Run `ego-browser --doctor` to verify your environment. This command checks for missing dependencies and reports any configuration issues that would prevent scripts from executing properly.

### Can I combine multiple flags when running ego-lite scripts?

Yes. Flags like `--reload` and `--debug-clicks` are designed to work together. For example: `ego-browser --reload --debug-clicks nodejs <<'EOF'` forces a fresh page load while logging all click interactions for debugging.

### Where are the browser automation helpers defined?

The `browser`, `page`, and `taskSpaces` helpers available in scripts are implemented in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). This file provides the Playwright-style API that JavaScript heredocs executed via `ego-browser nodejs` can call.

### What is the difference between npm test and npm run e2e?

`npm test` builds, type-checks, and runs the Node.js unit test suite using `node --test`. `npm run e2e` executes the separate task-space end-to-end test suite, which validates full browser automation workflows rather than individual functions.