name: ever-browser description: "Ever CLI browser control reference — commands and workflows for programmatic browser automation. Use this skill whenever the user wants to control a browser programmatically, use ever CLI commands, automate web interactions (clicking, typing, navigating, extracting), run autonomous browser tasks, or debug browser session issues."

Ever CLI — Browser Control

The ever CLI provides programmatic browser control through Chrome. Commands route: CLI → everd daemon → API server → extension CDPBridge → Chrome.

Quick Start

ever start --url https://example.com   # Create browser session
ever snapshot                           # Capture DOM with [id] annotations
ever click 42                           # Click element with ID 42
ever snapshot                           # Re-capture to see changes
ever stop                               # End session

Core Workflow: snapshot → act → snapshot

Every interaction follows this loop:

1. ever snapshot — capture annotated DOM with [id] markers on interactive elements (viewport + 500px buffer)
2. Act — perform action(s) using element IDs from the snapshot
3. ever snapshot — re-capture to see what changed (new elements marked with *[id] by default)

IMPORTANT: Always snapshot before interacting. Element IDs are only valid for the current snapshot. After page-changing actions (navigate, go-back, click on a link), you MUST snapshot again — old IDs are invalid.

Reading Snapshots

Snapshot output uses a tree notation for interactive elements:

[id]<TAG attrs>text</TAG>          — interactive element (use id for actions)
*[id]<TAG>                         — NEW element since last snapshot
|SCROLL[id]
                   — scrollable container
|SHADOW(open)|[id]<INPUT>          — element inside shadow DOM
  [child_id]<TAG>                  — tab-indented = child of element above

• Only elements with [id] can be targeted by actions
• Tree indentation shows parent-child hierarchy
• |SCROLL marks elements you can scroll inside (use ever scroll down --id <id>)
• |SHADOW marks shadow DOM boundaries — elements inside still get IDs and are actionable

Commands Reference

Session Management

DOM & Navigation

Interaction

Dropdown Handling

Native <select> elements cannot be clicked directly. Use these instead:

Content & Screenshots

When to use extract vs snapshot:

• Use snapshot when you need to find and interact with elements (returns [id] annotations)
• Use extract when you need to read content as clean text (returns markdown, no IDs)
• Prefer reading data from snapshot output directly when visible — extract is heavier

File Upload

Agent Tasks

Domain-Specific Commands

Google Sheets (ever sheets):

Agent File System (ever fs):

Auth & Config

Action Efficiency Guide

Action categories

• Page-changing (must be last): navigate, go-back, switch-tab, search — these load a new page. Element IDs from the previous snapshot become invalid. Always snapshot after.
• Potentially page-changing: click on links/buttons that navigate — may change the page. If it does, snapshot again.
• Safe to chain: input, scroll, wait, eval, select-dropdown, upload-file — do not change the page. Can be combined freely.

Efficient combinations

# Fill form and submit in sequence (input is safe, click-submit may navigate)

ever input 12 "John" && ever input 15 "john@example.com" && ever click 20

# Scroll multiple times to load lazy content

ever snapshot && ever scroll down && ever scroll down && ever snapshot

# Wait for dynamic content after triggering it

ever click 5 && ever wait 2 && ever snapshot --mode incremental

Common mistakes to avoid

• Don't use extract for data visible in snapshot — if the text is in the snapshot DOM tree, read it directly
• Don't click a <select> element — use get-dropdown-options + select-dropdown instead
• Don't forget to snapshot after navigation — old element IDs are stale
• Don't repeat failing actions — if clicking element X doesn't work, try a different approach (scroll to reveal it, use eval, try a different element)

Data Extraction with eval (Preferred for Scraping)

When the task is reading/scraping data (not clicking or interacting), use ever eval with custom JavaScript instead of snapshot. It's 10x faster and returns structured data directly.

Decision: snapshot vs eval vs extract

The Batch-Scroll-Collect Pattern

For scraping data across a scrollable feed (social media, search results, infinite scroll):

Step 1 — Initialize a global accumulator (avoids duplicates across scrolls):

ever eval "window._data = {}; window._cfg = { timeWindowMs: 5 * 60 * 60 * 1000 }; 'init ok'"

Step 2 — Collect + Scroll in a bash loop. Wrap in IIFE to avoid const redeclaration errors:

for i in $(seq 1 20); do
  ever scroll down 2>/dev/null
  sleep 1
  ever eval "(() => {
    // ... collect visible items into window._data ...
    return JSON.stringify({ collected: Object.keys(window._data).length });
  })()" 2>&1
done

Step 3 — Dump all collected data:

ever eval "JSON.stringify(Object.values(window._data), null, 2)"

Key rules for eval scripts

• Always wrap in IIFE (() => { ... })() — CDP eval shares scope across calls, const/let at top level will throw SyntaxError: already declared on subsequent runs
• Use window._varName for state that persists across eval calls (global accumulator, config)
• CDP eval has a ~30s timeout — don't put the scroll loop inside eval. Keep each eval call fast (<5s), do scrolling via ever scroll between calls
• Return JSON.stringify() — eval returns the expression's value as a string

Saved Recipes

Reusable eval scripts for common sites are saved in recipes/. Before writing a new scraper from scratch, check if a recipe exists:

To use a recipe: Read the recipe file for the INIT, COLLECT, and DUMP scripts. Adapt parameters (time window, selectors) as needed. The recipe documents which CSS selectors it relies on and when they were last verified.

To save a new recipe: After successfully scraping a site with eval, save the working script to recipes/<site>-<task>.js with the same format — header comments documenting site, selectors, and the INIT/COLLECT/DUMP pattern.

Common Patterns

Fill and submit a form

ever snapshot
ever input 12 "John Doe"
ever input 15 "john@example.com"
ever click 20                      # Submit button
ever snapshot                      # Verify result

Navigate and extract content

ever start --url https://example.com
ever snapshot
ever extract                       # Get full page as readable markdown
ever stop

Handle dynamic/delayed content

ever click 5                       # Trigger AJAX load
ever wait 2                        # Wait for content to load
ever snapshot --mode incremental   # See new elements

Scroll to find elements

ever snapshot
ever scroll down                   # Scroll one page
ever snapshot                      # Check for new elements

# Repeat until target found

Interact with shadow DOM elements

ever snapshot                      # Shadow DOM elements get [id] annotations too
ever input 347 "text"              # Use the [id] directly — works across shadow boundaries

Work with dropdown menus

ever snapshot                      # Find the <select> element [id]
ever get-dropdown-options 42       # List all options
ever select-dropdown 42 "United States"  # Select by text

Scrape data from a list across pages

# Preferred: use eval with batch-scroll-collect pattern (see "Data Extraction with eval" above)

# Fallback: snapshot-based approach for simple cases

ever snapshot                      # Read all visible items from snapshot
ever scroll down && ever snapshot  # Load more

# Continue until done

Run an autonomous task

ever start --url https://example.com
ever run "Find the pricing page and extract all plan details"

# Streams progress via SSE, prints stage updates

ever stop

Error Recovery