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

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, which handles argument parsing, stdin reading, and script execution.

# 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 (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

# 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 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) replaces console.log with a buffered sink, ensuring only cliLog() output reaches your terminal.

Complete CLI Usage Examples

Basic Page Navigation and Text Extraction

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 shows how to navigate, inspect, click, and capture:

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

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 and called from run.ts (lines 27-31).

# 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 – CLI entry point, argument parsing, and script execution orchestration
• package/ego-browser/src/helpers.ts – Helper implementations available to your scripts
• package/ego-browser/src/output-sink.ts – Output buffering and flushing mechanism
• 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). 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) replaces console.log with a buffered sink that only flushes on successful completion. Always use cliLog() for guaranteed immediate output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}