Neo 2.0 — Web App API Discovery & Browser Automation

Neo turns any website into an AI-callable API. Zero extensions required — pure CDP.

⚠️ MANDATORY FIRST STEP

neo doctor

• All ✓ → proceed
• Chrome CDP ✗ → neo start (launches Chrome with correct profile + CDP)
• Still ✗ → ask the user, then STOP. Don't loop.

Critical Rules

1. NEVER start Chrome manually — always neo start
2. NEVER copy Chrome profiles — login sessions live in the real profile
3. NEVER pkill chrome — user may have important tabs open
4. If stuck → tell user, STOP. Don't retry in a loop.

Workflows

Read a web page

neo doctor
neo read example.com          # Extract readable text from any open tab
# If page isn't open:
neo open https://example.com
neo read example.com

Call a website's API (fast path)

neo doctor
neo schema show x.com                   # Check existing API knowledge
neo api x.com HomeTimeline              # Call it (auto-auth from browser)
neo api x.com CreateTweet --body '{"variables":{"tweet_text":"hello"}}'

Discover APIs for a new website

neo doctor
neo open https://example.com            # Open in Chrome
# Browse around to generate traffic
neo capture list example.com --limit 20
neo schema generate example.com
neo api example.com <keyword>

UI automation (click/fill/type — when no API exists)

neo doctor
neo snapshot                  # Get a11y tree with compact ref IDs
neo click 14                  # Click element by ref number
neo fill 7 "search query"    # Clear + fill input
neo type 7 "text"             # Append text
neo press Enter
neo scroll down 500
neo screenshot

Refs are compact integers: [0] button "Sign in", [1] input "Search". Use neo click 0, neo fill 1 "query" etc. Legacy @e5 and [5] formats also work.

Cookie management

neo cookies list                        # All cookies for active page
neo cookies list github.com             # Filter by domain
neo cookies export github.com cookies.json  # Save to file
neo cookies import cookies.json         # Restore cookies
neo cookies clear github.com            # Delete by domain
neo cookies clear                       # Delete all

Use export + import to persist login sessions across browser restarts.

Profile management

neo profile list              # Discover all Chrome profiles + emails
neo profile use "Default"     # Set default profile
neo start                     # Launches with selected profile

Clean up — close tabs when done

neo tabs
neo eval "window.close()" --tab example.com

Command Reference

# Page Reading & Interaction
neo open <url>                          # Open URL in Chrome
neo read <tab-pattern>                  # Extract readable text
neo eval "<js>" --tab <pattern>         # Run JS in page context
neo tabs [filter]                       # List open Chrome tabs

# UI Automation (compact refs: neo click 5, neo fill 3 "text")
neo snapshot [-i] [-C] [--json] [--diff]  # A11y tree with compact refs
neo click <ref> [--new-tab]             # Click element
neo fill <ref> "text"                   # Clear + fill input
neo type <ref> "text"                   # Append text to input
neo press <key>                         # Keyboard key (Ctrl+a, Enter, etc.)
neo hover <ref>                         # Hover
neo scroll <dir> [px] [--selector css]  # Scroll
neo select <ref> "value"               # Select dropdown
neo screenshot [path] [--full]          # Capture screenshot
neo get text <ref> | url | title        # Extract info
neo wait <ref> | --load | <ms>          # Wait for element/load/time

# Cookie Management
neo cookies list [domain]               # List cookies
neo cookies export [domain] [file]      # Export as JSON
neo cookies import <file>               # Import from JSON
neo cookies clear [domain]              # Clear cookies

# Profile Management
neo profile list                        # Discover Chrome profiles
neo profile use <name>                  # Set default profile

# Capture & Traffic (no extension needed — pure CDP)
neo status                              # Overview
neo capture start                       # Start CDP network capture
neo capture stop                        # Stop capture
neo capture list [domain] [--limit N]   # Recent captures
neo capture search <query>              # Search by URL pattern
neo capture domains                     # Domains with counts
neo capture detail <id>                 # Full capture details

# Schema (API Knowledge)
neo schema generate <domain>            # Generate from captures
neo schema show <domain>                # Human-readable
neo schema list                         # All cached schemas
neo schema search <query>               # Search endpoints

# API Execution
neo api <domain> <keyword> [--body '{}']  # Smart call (schema + auto-auth)
neo exec <url> [--method POST] [--body] [--tab pattern] [--auto-headers]
neo replay <id> [--tab pattern]         # Replay captured call

# Setup & Diagnostics
neo setup                               # First-time setup
neo start [--profile <name>]            # Launch Chrome with correct profile + CDP
neo doctor [--fix]                      # Health check (--fix to auto-repair)

Decision Tree

Want to interact with a website?
  │
  ├─ FIRST: neo doctor
  │   ├─ All ✓ → continue
  │   ├─ Chrome ✗ → neo start → retry
  │   └─ Still ✗ → ask user, STOP
  │
  ├─ Just read content? → neo read <domain>
  │
  ├─ Need to call an API?
  │   ├─ neo schema show <domain> → exists? → neo api
  │   └─ No schema? → neo open → browse → neo schema generate → neo api
  │
  ├─ Need to click/fill/type?
  │   └─ neo snapshot → neo click 5 / neo fill 3 "text"
  │
  ├─ Need to manage cookies/sessions?
  │   └─ neo cookies list/export/import/clear
  │
  └─ Done? → neo eval "window.close()" --tab <domain>

Key Principles

1. neo doctor first, always.
2. API > UI automation. If schema has it, use neo api. Don't snapshot+click.
3. Auth is automatic. API calls inherit browser cookies/session/CSRF.
4. Close tabs after use. Every neo open creates a new tab.
5. If stuck, stop. Don't loop on Chrome startup. Ask the user.