surf-cli 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,14 @@
+<p>
+  <img src="surf-banner.png" alt="surf" width="1100">
+</p>
+
 # Surf
 
-The CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.
+**The CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.**
+
+[![npm version](https://img.shields.io/npm/v/surf-cli?style=for-the-badge)](https://www.npmjs.com/package/surf-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue?style=for-the-badge)]()
 
 ```bash
 surf go "https://example.com"
@@ -23,7 +31,7 @@ Surf takes a different approach:
 
 **Smart Defaults** - Screenshots auto-resize to 1200px (saves tokens). Actions auto-capture screenshots (saves round-trips). Errors on restricted pages warn instead of fail.
 
-**AI Without API Keys** - Query ChatGPT, Gemini, and Perplexity using your browser's logged-in session. No API keys, no rate limits, no cost.
+**AI Without API Keys** - Query ChatGPT, Gemini, Perplexity, and Grok using your existing browser logins. No API keys needed.
 
 **Network Capture** - Automatically logs all network requests while active. Filter, search, and replay API calls without manually setting up request interception.
 
@@ -298,9 +306,20 @@ surf perplexity "what is quantum computing"
 surf perplexity "explain this page" --with-page               # Include page context
 surf perplexity "deep dive" --mode research                   # Research mode (Pro)
 surf perplexity "latest news" --model sonar                   # Model selection (Pro)
+
+# Grok (queries x.com/i/grok using your X.com login)
+surf grok "what are the latest AI agent trends on X"          # Search X posts
+surf grok "analyze @username recent activity"                 # Profile analysis
+surf grok "summarize this page" --with-page                   # Include page context
+surf grok "find viral AI posts" --deep-search                 # DeepSearch mode
+surf grok "quick question" --model fast                       # Models: auto, fast, expert, thinking
+surf grok --validate                                          # Check UI and available models
+surf grok --validate --save-models                            # Save discovered models to settings
 ```
 
-Requires being logged into chatgpt.com, gemini.google.com, or perplexity.ai in Chrome.
+Each AI tool uses your existing browser login - no API keys needed. Just be logged into the respective service in Chrome (chatgpt.com, gemini.google.com, perplexity.ai, or x.com).
+
+**Grok troubleshooting:** If queries fail, run `surf grok --validate` to check if the UI structure changed. Use `--save-models` to update the model cache in `surf.json`. Default model is "thinking" (Grok 4.1 Thinking).
 
 ### Waiting
 
@@ -354,6 +373,55 @@ surf network.stats                    # Capture statistics
 Storage location: `/tmp/surf/` (override with `--network-path` or `SURF_NETWORK_PATH` env).
 Auto-cleanup: 24 hours TTL, 200MB max.
 
+### Workflows
+
+Execute multi-step browser automation as a single command:
+
+```bash
+# Inline workflow (newline-separated commands)
+surf do 'go "https://example.com/login"
+type "user@example.com" --selector "input[name=email]"
+type "password123" --selector "input[name=password]"
+click --selector "button[type=submit]"
+screenshot --output /tmp/after-login.png'
+
+# From JSON file (same format as --script)
+surf do --file login-workflow.json
+
+# Validate without executing
+surf do 'go "url"\nclick e5\nscreenshot' --dry-run
+```
+
+**Why workflows?** Instead of 6-8 separate CLI calls with LLM orchestration between each step, a workflow executes deterministically with smart auto-waits. Faster, cheaper, and more reliable.
+
+**Options:**
+- `--file`, `-f` - Load workflow from JSON file
+- `--dry-run` - Parse and validate without executing
+- `--on-error stop|continue` - Error handling (default: stop)
+- `--step-delay <ms>` - Delay between steps (default: 100, use 0 to disable)
+- `--no-auto-wait` - Disable automatic waits between steps
+- `--json` - Output structured JSON result
+
+**Auto-waits:** Commands that trigger page changes automatically wait for completion:
+- Navigation (`go`, `back`, `forward`) → waits for page load
+- Clicks, key presses, form fills → waits for DOM stability
+- Tab switches → waits for tab to load
+
+**JSON file format:**
+```json
+{
+  "name": "Login Flow",
+  "steps": [
+    { "tool": "navigate", "args": { "url": "https://example.com/login" } },
+    { "tool": "type", "args": { "text": "user@example.com", "selector": "input[name=email]" } },
+    { "tool": "click", "args": { "selector": "button[type=submit]" } },
+    { "tool": "screenshot", "args": {} }
+  ]
+}
+```
+
+**Supported commands:** All surf commands work in workflows. Use aliases (`go`, `snap`, `read`) or full names (`navigate`, `screenshot`, `page.read`).
+
 ## Global Options
 
 ```bash
@@ -374,10 +442,50 @@ For programmatic integration, send JSON to `/tmp/surf.sock`:
 echo '{"type":"tool_request","method":"execute_tool","params":{"tool":"tab.list","args":{}},"id":"1"}' | nc -U /tmp/surf.sock
 ```
 
+### Protocol Reference
+
+**Request:**
+```json
+{
+  "type": "tool_request",
+  "method": "execute_tool",
+  "params": {
+    "tool": "click",
+    "args": { "ref": "e5" }
+  },
+  "id": "unique-request-id",
+  "tabId": 123,
+  "windowId": 456
+}
+```
+
+**Success Response:**
+```json
+{
+  "type": "tool_response",
+  "id": "unique-request-id",
+  "result": {
+    "content": [{ "type": "text", "text": "Result message" }]
+  }
+}
+```
+
+**Error Response:**
+```json
+{
+  "type": "tool_response",
+  "id": "unique-request-id",
+  "error": {
+    "content": [{ "type": "text", "text": "Error message" }]
+  }
+}
+```
+
 ## Command Groups
 
 | Group | Commands |
 |-------|----------|
+| `workflow` | `do` |
 | `window.*` | `new`, `list`, `focus`, `close`, `resize` |
 | `tab.*` | `list`, `new`, `switch`, `close`, `name`, `unname`, `named`, `group`, `ungroup`, `groups`, `reload` |
 | `scroll.*` | `top`, `bottom`, `to`, `info` |
@@ -438,6 +546,20 @@ surf install <extension-id> --browser chromium
 - Screenshot resize uses ImageMagick instead of macOS `sips`
 - Headless servers need Xvfb + VNC for initial login setup
 
+## AI Agent Integration
+
+Surf includes a skill file for AI coding agents like [Pi](https://github.com/badlogic/pi-mono):
+
+```bash
+# Symlink for auto-updates
+ln -s "$(pwd)/skills/surf" ~/.pi/agent/skills/surf
+
+# Or copy
+cp -r skills/surf ~/.pi/agent/skills/
+```
+
+See [`skills/README.md`](skills/README.md) for details.
+
 ## Development
 
 ```bash