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

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. The entry point lives at 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.

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.

-h, --help — Display Usage Information

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

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.

ego-browser --doctor

--reload — Force Page Reload

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

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.

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
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.

# 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 — CLI entry point; handles flag parsing, STDIN consumption, helper injection, and script execution
• src/helpers.ts — Implements the public API (page, browser, taskSpaces) available to user scripts
• README.md — Build/run workflow documentation and usage examples
• package.json — Declares the ego-browser binary and npm script definitions

Typical Workflow Examples

Combine flags for common development scenarios:

Fresh start with debugging:

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:

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 and 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. 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.

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