Headless & CLI

Egg ships two command-line binaries. egg launches the browser (with or without a window) and runs short headless tasks like screenshots, PDF rendering, and data exports. egg-daemon manages the persistent gateway service: start, stop, inspect status, pin a port for development.

Headless mode runs the full browser engine without showing a window. You get the same rendering, cookies, sessions, extensions, and privacy posture an interactive Egg session has, just without the UI. That makes it useful for scripted automation: capture a full-page screenshot from a CI job, render a styled invoice to PDF, dump the rendered DOM after JavaScript runs, or pull a reader-mode extraction of an article. Each task flag implies --headless and exits when the task finishes, so the binary works as a one-shot in shell pipelines.

Both binaries accept Chrome-style flags, and unrecognized --* flags forward to the underlying engine. Most existing Chromium tooling and command-line patterns work without changes; the differences are documented inline.

egg

Open a URL, run a headless task, or export data.

# Open a URL (positional or --url=)
egg https://eggbrowser.com/
egg --url=https://eggbrowser.com/

# Open as a chromeless app window
egg --app=https://eggbrowser.com/

# Help / version
egg --help
egg --version

General

Window

Privacy & sessions

Headless tasks

Each task flag implies --headless. Default timeout is 30000 ms; exit code 124 on timeout.

Automation

Advanced

Recipes

# Full-page screenshot
egg --screenshot=out.png https://eggbrowser.com/

# PDF render with a custom viewport
egg --print-to-pdf=invoice.pdf --window-size=1280x1600 https://invoices.example.com/

# Pipe rendered HTML into another tool
egg --dump-dom https://news.ycombinator.com/ | htmlq '.athing'

# Reader-mode extraction
egg --extract-page https://en.wikipedia.org/wiki/Browser

# Export data
egg --export-bookmarks=bookmarks.json
egg --export-history=history.csv
EGG_VAULT_PASSWORD="..." egg --export-passwords=secrets.csv

# Open as a focused PWA window
egg --app=https://app.example.com/ --window-size=1100x800

# Attach a CDP client
egg --remote-debugging-port=9222 https://example.com/
curl http://127.0.0.1:9222/json/version

Chromium passthrough

Unknown --* flags forward to the underlying engine via WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS. Pass --strict-flags to reject unknowns instead.

# Forwarded to Chromium
egg --proxy-server=socks5://127.0.0.1:1080 https://example.com/
egg --lang=en-US --disable-features=Translate

# Strict mode rejects unknowns
egg --strict-flags --bogus-flag
# → exit 2: unknown flag --bogus-flag

• If a passthrough flag conflicts with Egg’s privacy hardening, the user’s flag wins. A WARN is written to the log.
• Vault passwords and similar secrets are read from environment variables, never flags. Process listings and shell history would leak them otherwise.

egg-daemon

The persistent gateway service. The browser auto-launches it; you can also run it directly to inspect state, terminate it, or pin port + token for development.

# Boot in foreground (logs to stdout)
egg-daemon

# JSON status of the running instance
egg-daemon --status

# Terminate the running daemon
egg-daemon --kill

# Pin port + token
egg-daemon --port=19999 --token=devtoken

Lifecycle

Status & control