How to Start ego-browser in CLI Mode: Command-Line Automation Guide

Run ego-browser nodejs <<'EOF' ... EOF to execute JavaScript inside the embedded browser via command line, leveraging Playwright-style APIs for web automation.

The ego-browser executable from the citrolabs/ego-lite repository provides a command-line interface for browser automation without requiring a GUI. When started in ego-browser CLI mode, the runtime reads JavaScript from STDIN, injects a helper context with browser controls, and executes the script within an embedded Chromium instance. This architecture enables headless web automation, automated testing, and data extraction through simple shell commands and heredocs.

Understanding the CLI Detection Architecture

The entry point for CLI mode is located in package/ego-browser/src/index.ts. When you invoke the ego-browser binary directly, the script detects this scenario using the isDirectCli() helper function (lines 75-78).

If the check succeeds, the runtime immediately executes runMain() (lines 56-63) and exits with the return code from that execution. This flow ensures that the Node.js helper runtime embedded in the binary initializes correctly and prepares the environment for script execution.

Starting a CLI Session with the nodejs Subcommand

The canonical way to start ego-browser in CLI mode is using the nodejs subcommand, which tells the runtime to treat the following heredoc as executable JavaScript. The binary reads this input via STDIN, creates the helper context through helperContext(), and runs the code inside the browser environment.

Use the following syntax to execute a script:

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

When the script completes, output captured through console.log is printed to the terminal via the buffered output sink, and the process exits with the script's return code. You can also invoke the binary without arguments, as it falls back to the same detection logic and runMain() execution.

Accessing Global Helpers and Browser APIs

Scripts executed in CLI mode have access to Playwright-style facades defined in package/ego-browser/src/helpers.ts. These globals are automatically injected into the execution context before your script runs:

• taskSpaces – Manages isolated browser contexts and task spaces.
• browser – Controls browser-level operations such as creating new tabs.
• page – Provides page interaction methods like fill(), press(), and snapshot().

The runMain() function in package/ego-browser/src/run.ts handles the STDIN reading and context injection, making these helpers available without explicit imports in your CLI scripts.

Debugging Scripts Locally Without the Browser

For development and debugging, you can invoke the built JavaScript bundle directly with Node.js to test logic without launching the full browser environment. This is useful for validating helper syntax or testing non-browser-specific code.

Navigate to the package directory and run:

node dist/out/index.js <<'JS'
console.log(await page.info())
JS

This local invocation method bypasses the isDirectCli() detection and executes against the helper bundle directly, as documented in the package-level README.

Summary

• Entry detection: The runtime checks isDirectCli() in package/ego-browser/src/index.ts to determine if it should execute in CLI mode.
• Execution flow: runMain() reads STDIN, injects the helper context, and runs the script, exiting with the script's return code.
• Standard invocation: Use ego-browser nodejs followed by a heredoc to execute JavaScript in the embedded browser.
• Available APIs: Global objects taskSpaces, browser, and page from package/ego-browser/src/helpers.ts provide Playwright-compatible automation methods.
• Local debugging: Run node dist/out/index.js directly to test scripts without spawning the browser process.

Frequently Asked Questions

What is ego-browser CLI mode and how does it work?

ego-browser CLI mode is a headless execution environment where the binary reads JavaScript code from STDIN and runs it inside an embedded Chromium browser. The isDirectCli() function in package/ego-browser/src/index.ts (lines 75-78) detects direct binary invocation, triggering runMain() to process the input script and inject the helper context before execution.

Which subcommands are available when starting ego-browser from the command line?

While the binary supports direct invocation without arguments (falling back to runMain()), the primary documented subcommand is nodejs. This subcommand explicitly signals the runtime to parse the following heredoc as JavaScript that will execute within the browser automation context.

How can I debug ego-browser scripts without launching the actual browser?

You can debug the helper bundle locally by executing the compiled output directly with Node.js: node dist/out/index.js. This method allows you to verify script syntax and test helper API calls without the overhead of browser initialization, as the entry point skips the browser-specific initialization code path.

What browser automation APIs are available in CLI scripts?

CLI scripts have access to three main global objects defined in package/ego-browser/src/helpers.ts: taskSpaces for context management, browser for tab and window control, and page for element interaction. These provide Playwright-compatible methods such as openOrReuseTab(), fill(), press(), and snapshot().

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