neo

# 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

```bash
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

```bash
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)

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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

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

## Command Reference

```bash
# 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.