# How to Use the ego-lite Command-Line Interface (CLI): A Complete Guide

> Learn to use the ego-lite command-line interface CLI to run JavaScript against an embedded browser runtime. This complete guide covers the ego-browser skill.

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

---

**The ego-lite CLI is provided by the `ego-browser` skill and runs a Node.js harness that reads JavaScript from stdin and executes it against the embedded browser runtime.**

The **ego-lite CLI** gives you direct command-line control over a headless Chrome browser embedded in the ego-lite application. Unlike traditional Selenium-based workflows, no external driver is required—commands execute through Chrome DevTools Protocol (CDP) under the hood. This guide explains how to install, configure, and automate browser tasks using the `ego-browser` CLI tool.

## CLI Installation and Entry Point

The CLI lives in the `ego-browser` package within the citrolabs/ego-lite repository. The main entry point is `runMain()` in [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts), which handles argument parsing, stdin reading, and script execution.

```bash

# The CLI is invoked as

ego-browser [flags] nodejs <<'EOF'
// JavaScript code here
EOF

```

The `runMain()` function performs three core operations:
- Parses command-line flags
- Reads your script from stdin via heredoc
- Evaluates the code in an async context with pre-loaded helpers

## Supported Command-Line Flags

The CLI recognizes several flags defined in [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts) (lines 73-84):

| Flag | Purpose |
|------|---------|
| `--help` / `-h` | Displays help text stored in the `HELP` constant |
| `--doctor` | Runs `runDoctor()` to diagnose browser connectivity |
| `--reload` | Resets the browser connection on next invocation |
| `--debug-clicks` | Enables click debugging by setting `EGO_BROWSER_DEBUG_CLICKS=1` |

```bash

# Check CLI help

ego-browser --help

# Diagnose browser connection health

ego-browser --doctor

# Reset connection state

ego-browser --reload

# Enable click coordinate logging

ego-browser --debug-clicks nodejs <<'EOF'
await openOrReuseTab('https://example.com')
await click('@12')
EOF

```

## Writing JavaScript Scripts for the CLI

When no flag is given, the CLI expects a JavaScript heredoc. Your code executes in a sandbox where **ego-browser helpers** are automatically available. These helpers—defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) and injected via `executionContext()`—include:

- `openOrReuseTab(url, options)` – Navigate or create a tab
- `click(selectorOrRef, options)` – Click elements by CSS selector or `@ref`
- `snapshotText()` – Extract rendered page text with element references
- `captureScreenshot(options)` – Save viewport or full-page screenshots
- `useOrCreateTaskSpace(name)` – Manage isolated browsing sessions
- `cliLog(message)` – Buffer output for terminal display

The `executionContext()` function (lines 33-47 in [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts)) replaces `console.log` with a buffered sink, ensuring only `cliLog()` output reaches your terminal.

## Complete CLI Usage Examples

### Basic Page Navigation and Text Extraction

```bash
ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('demo')
await openOrReuseTab('https://example.com', { wait: true })
cliLog('--- Page content ---')
cliLog(await snapshotText())
cliLog('--- End ---')
EOF

```

### Interactive Clicking and Screenshot Capture

This pattern from [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) shows how to navigate, inspect, click, and capture:

```bash
ego-browser nodejs <<'EOF'
await openOrReuseTab('https://news.ycombinator.com', { wait: true })
const txt = await snapshotText()
cliLog(txt)  // Shows numbered refs like @12, @13 for interactive elements

await click('@12', { label: 'open top story' })
await captureScreenshot({ path: '/tmp/hn.png' })
cliLog('Screenshot saved to /tmp/hn.png')
EOF

```

### Debugging Click Coordinates

```bash
ego-browser --debug-clicks nodejs <<'EOF'
await openOrReuseTab('https://github.com', { wait: true })
await click('button[data-hotkey="c"]', { label: 'Create repo' })
EOF

```

## Output Handling and Error Behavior

After your script resolves, `flushSink()` writes buffered output to stdout. If your script throws, the sink is discarded and the error propagates to the terminal. This is implemented in [`package/ego-browser/src/output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts) and called from [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts) (lines 27-31).

```bash

# Successful execution: output prints

ego-browser nodejs <<'EOF'
cliLog('This appears in terminal')
EOF

# Failed execution: error propagates, no partial output

ego-browser nodejs <<'EOF'
cliLog('This never prints')
throw new Error('Script fails')
EOF

```

## Key Source Files in ego-lite

Understanding these files helps extend or debug CLI behavior:

- **[`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts)** – CLI entry point, argument parsing, and script execution orchestration
- **[`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)** – Helper implementations available to your scripts
- **[`package/ego-browser/src/output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts)** – Output buffering and flushing mechanism
- **[`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md)** – Official documentation with heredoc patterns and helper reference

## Summary

- The **ego-lite CLI** is the `ego-browser` command, not a separate binary
- Scripts are passed via **stdin heredocs**, not file arguments
- **Pre-loaded helpers** eliminate boilerplate for common browser automation tasks
- Use **`cliLog()`** for guaranteed terminal output; `console.log` is buffered and may be suppressed
- The **`--debug-clicks`** flag aids troubleshooting coordinate-based interactions
- No external Chrome or driver installation is required—the runtime is embedded in ego-lite

## Frequently Asked Questions

### How do I pass a JavaScript file to the ego-lite CLI instead of a heredoc?

The CLI reads exclusively from stdin via `process.stdin` (lines 98-106 in [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts)). Use shell redirection: `ego-browser nodejs < script.js` or wrap file contents in a heredoc: `ego-browser nodejs <<EOF $(cat script.js) EOF`.

### What happens if the browser crashes during script execution?

The `runMain()` function wraps execution in try/catch blocks. Errors propagate to stderr and the process exits non-zero. Use `--reload` to reset the CDP connection if the browser becomes unresponsive.

### Can I use external npm packages in my CLI scripts?

No—the script runs in a controlled sandbox with only the injected helpers from `helperContext`. For external dependencies, pre-bundle your code or use the ego-lite skill system rather than the CLI directly.

### Why does `console.log` not appear in my terminal output?

The `executionContext()` function (lines 33-47 in [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts)) replaces `console.log` with a buffered sink that only flushes on successful completion. Always use **`cliLog()`** for guaranteed immediate output.