Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: update get-started.md for orchestrator architecture

Mario6ac72238b35f
diff --git a/docs/get-started.md b/docs/get-started.md
index 7622b500..0649d994 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -60,7 +60,7 @@ go build -o pinchtab ./cmd/pinchtab
## Quick Start (5 Minutes)
-### Step 1: Start the Server
+### Step 1: Start the Orchestrator
**Terminal 1:**
```bash
@@ -69,41 +69,35 @@ pinchtab
**Expected output:**
```
-πŸ¦€ PINCH! PINCH! port=9867 cdp= stealth=light
-auth disabled (set BRIDGE_TOKEN to enable)
-startup configuration bind=127.0.0.1 port=9867 headless=true ...
+πŸ¦€ Pinchtab Dashboard port=9867
+dashboard ready url=http://localhost:9867/dashboard
```
-The server is running on `http://127.0.0.1:9867`.
+The orchestrator is running on `http://127.0.0.1:9867`. Open the dashboard in your browser to see instances and profiles.
-### Step 2: Run Your First Command
+### Step 2: Create an Instance
**Terminal 2:**
```bash
-pinchtab quick https://example.com
-```
-
-**What happens:**
-1. Navigates to the URL
-2. Shows page structure
-3. Lists interactive elements
-4. Suggests next actions
+# Create a headless instance (background Chrome)
+INST=$(pinchtab instance launch --mode headless | jq -r '.id')
+echo "Instance created: $INST"
-**Output:**
+# Wait for Chrome to initialize (~2-5 seconds)
+sleep 3
```
-πŸ¦€ Navigating to https://example.com ...
-πŸ“‹ Page structure:
-[accessibility tree...]
+### Step 3: Run Your First Command
+
+```bash
+# Navigate to a website
+pinchtab instance navigate $INST https://example.com
-πŸ“Œ Title: Example Domain
-πŸ”— URL: https://example.com/
+# Get page structure
+curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({role, name}) | .[0:5]'
-πŸ’‘ Quick actions:
- pinchtab click <ref> # Click an element
- pinchtab type <ref> <text> # Type into input
- pinchtab screenshot # Take a screenshot
- pinchtab pdf -o output.pdf # Save as PDF
+# Extract text
+curl http://localhost:9867/instances/$INST/text | jq '.text'
```
βœ… **You're running PinchTab!**
@@ -115,102 +109,124 @@ pinchtab quick https://example.com
### Get Page Content
```bash
-# Read the page as text
-pinchtab text
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
-# See interactive elements
-pinchtab snap -i -c
+# Navigate
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
-# Get raw HTML content
-pinchtab text --raw
+# Read the page as text
+curl http://localhost:9867/instances/$INST/text
+
+# Get interactive elements (snapshot)
+curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({ref, role, name})'
```
### Take a Screenshot
```bash
# Save screenshot
-pinchtab screenshot -o page.jpg
+curl http://localhost:9867/instances/$INST/screenshot -o page.png
-# Lower quality
-pinchtab screenshot -o page.jpg -q 75
+# For curl, specify tab if multiple tabs exist
+curl "http://localhost:9867/instances/$INST/screenshot?tabId=$TAB_ID" -o page.png
```
### Export as PDF
```bash
-pinchtab pdf -o output.pdf
-pinchtab pdf -o report.pdf --landscape
+# Save PDF
+curl "http://localhost:9867/instances/$INST/pdf?landscape=true" -o output.pdf
```
### Interact with the Page
```bash
-# First, get interactive elements
-pinchtab snap -i -c
-
-# Then click one (replace 'e5' with a real ref)
-pinchtab click e5
+# Get page structure (snapshot)
+SNAPSHOT=$(curl http://localhost:9867/instances/$INST/snapshot)
-# Verify the change
-pinchtab snap -i -c
+# Extract a reference (e.g., first button)
+BUTTON_REF=$(echo "$SNAPSHOT" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)
-# Or fill a form
-pinchtab fill e3 "[email protected]"
-pinchtab fill e5 "password"
+# Click the button
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"click","ref":"'$BUTTON_REF'"}'
-# Submit button
-pinchtab click e7
+# Or fill a form input
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"fill","ref":"e3","text":"[email protected]"}'
```
### Multiple Tabs
```bash
-# Open second tab
-pinchtab tabs new https://github.com
+# Create new tab in instance
+curl -X POST http://localhost:9867/tabs/open \
+ -H "Content-Type: application/json" \
+ -d '{"instanceId":"'$INST'","url":"https://github.com"}'
# List all tabs
-pinchtab tabs
+curl http://localhost:9867/tabs
-# Get snapshot from specific tab (replace tabId)
-pinchtab snap --tab abc123def456
+# Operate on specific tab
+TAB_ID=$(curl http://localhost:9867/instances/$INST/tabs | jq -r '.[0].id')
+
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"e5","tabId":"'$TAB_ID'"}'
```
---
## Understanding the Workflow
-### Key Concept: Tab-Centric
+### Key Concepts
-PinchTab is **tab-centric**, not URL-centric:
+**Orchestrator** (port 9867):
+- Manages instances
+- Routes requests via `/instances/{id}/*`
+- No Chrome process itself
-```
-❌ WRONG: pinchtab snap https://example.com
-βœ… CORRECT:
- 1. pinchtab nav https://example.com (uses current tab)
- 2. pinchtab snap (snapshots current tab)
-```
+**Instance** (ports 9868-9968):
+- Real Chrome browser process
+- Has one or more tabs
+- Isolated cookies, history, storage
+- Each has unique ID: `inst_XXXXXXXX`
-**Why?** Because a tab has state (cookies, history, focus, loaded content). Multiple tabs can exist. You need to specify which tab to work with.
+**Tab**:
+- Single webpage within instance
+- Has state (URL, DOM, focus, content)
+- Unique ID: `tab_XXXXXXXX`
### Typical Workflow
```bash
-# 1. Navigate to a page
-pinchtab nav https://example.com
+# 1. Create instance (Chrome starts lazily on first request)
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
+
+# 2. Navigate to a page
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
-# 2. Get page structure (see buttons, links, inputs)
-pinchtab snap -i -c
+# 3. Get page structure (see buttons, links, inputs)
+curl http://localhost:9867/instances/$INST/snapshot
-# 3. Interact with page
-pinchtab click e5
-pinchtab type e3 "text"
+# 4. Interact with page (click, type, etc.)
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"e5"}'
-# 4. Verify changes
-pinchtab snap -i -c
+# 5. Verify changes
+curl http://localhost:9867/instances/$INST/snapshot
-# 5. Capture result
-pinchtab screenshot
-pinchtab pdf -o out.pdf
+# 6. Capture result
+curl http://localhost:9867/instances/$INST/screenshot -o page.png
+curl http://localhost:9867/instances/$INST/pdf -o report.pdf
+
+# 7. Stop instance (clean up)
+curl -X POST http://localhost:9867/instances/$INST/stop
```
---
@@ -223,19 +239,27 @@ You don't need the CLI. PinchTab is HTTP:
# Health check
curl http://localhost:9867/health
-# Navigate (returns tabId)
-curl -X POST http://localhost:9867/tab \
+# Create instance
+INST=$(curl -s -X POST http://localhost:9867/instances/launch | jq -r '.id')
+sleep 2
+
+# Navigate
+curl -X POST http://localhost:9867/instances/$INST/navigate \
-H "Content-Type: application/json" \
- -d '{"action":"new","url":"https://example.com"}'
+ -d '{"url":"https://example.com"}'
# Get snapshot
-curl "http://localhost:9867/snapshot?tabId=abc123"
+curl http://localhost:9867/instances/$INST/snapshot
# Extract text
-curl "http://localhost:9867/text?tabId=abc123"
+curl http://localhost:9867/instances/$INST/text
+
+# Stop instance
+curl -X POST http://localhost:9867/instances/$INST/stop
```
-**Full API reference** β†’ [curl-commands.md](references/curl-commands.md)
+**Full API reference** β†’ [curl-commands.md](references/curl-commands.md)
+**Instance API details** β†’ [instance-api.md](references/instance-api.md)
---
@@ -244,32 +268,45 @@ curl "http://localhost:9867/text?tabId=abc123"
```python
import requests
import json
+import time
BASE = "http://localhost:9867"
-# Create tab + navigate
-resp = requests.post(f"{BASE}/tab", json={
- "action": "new",
+# 1. Create instance
+resp = requests.post(f"{BASE}/instances/launch", json={"mode": "headless"})
+inst_id = resp.json()["id"]
+print(f"Created instance: {inst_id}")
+
+# Wait for Chrome to initialize
+time.sleep(2)
+
+# 2. Navigate
+resp = requests.post(f"{BASE}/instances/{inst_id}/navigate", json={
"url": "https://example.com"
})
-tab_id = resp.json()["tabId"]
+print(f"Navigated: {resp.json()}")
-# Get snapshot
-snapshot = requests.get(f"{BASE}/snapshot", params={
- "tabId": tab_id,
- "filter": "interactive"
-}).json()
+# 3. Get snapshot
+snapshot = requests.get(f"{BASE}/instances/{inst_id}/snapshot").json()
# Print interactive elements
-for elem in snapshot["elements"]:
- print(f"{elem['ref']}: {elem['role']} - {elem['name']}")
+for elem in snapshot.get("nodes", []):
+ if elem.get("role") in ["button", "link"]:
+ print(f"{elem['ref']}: {elem['role']} - {elem['name']}")
-# Click an element
-requests.post(f"{BASE}/action", json={
+# 4. Click an element
+requests.post(f"{BASE}/instances/{inst_id}/action", json={
"kind": "click",
- "ref": "e5",
- "tabId": tab_id
+ "ref": "e5"
})
+
+# 5. Get text
+text = requests.get(f"{BASE}/instances/{inst_id}/text").json()
+print(f"Page text: {text['text'][:200]}...")
+
+# 6. Stop instance
+requests.post(f"{BASE}/instances/{inst_id}/stop")
+print(f"Stopped instance: {inst_id}")
```
---
@@ -282,34 +319,62 @@ const fetch = require('node-fetch');
const BASE = "http://localhost:9867";
async function main() {
- // Create tab
- const navResp = await fetch(`${BASE}/tab`, {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- action: "new",
- url: "https://example.com"
- })
- });
- const nav = await navResp.json();
- const tabId = nav.tabId;
-
- // Get snapshot
- const snapResp = await fetch(
- `${BASE}/snapshot?tabId=${tabId}&filter=interactive`
- );
- const snap = await snapResp.json();
-
- // Click element
- await fetch(`${BASE}/action`, {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- kind: "click",
- ref: "e5",
- tabId: tabId
- })
- });
+ try {
+ // 1. Create instance
+ const launchResp = await fetch(`${BASE}/instances/launch`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ mode: "headless" })
+ });
+ const launch = await launchResp.json();
+ const instId = launch.id;
+ console.log(`Created instance: ${instId}`);
+
+ // Wait for Chrome to initialize
+ await new Promise(r => setTimeout(r, 2000));
+
+ // 2. Navigate
+ await fetch(`${BASE}/instances/${instId}/navigate`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ url: "https://example.com"
+ })
+ });
+
+ // 3. Get snapshot
+ const snapResp = await fetch(`${BASE}/instances/${instId}/snapshot`);
+ const snap = await snapResp.json();
+
+ // Print interactive elements
+ snap.nodes
+ .filter(n => ["button", "link"].includes(n.role))
+ .forEach(n => console.log(`${n.ref}: ${n.role} - ${n.name}`));
+
+ // 4. Click element
+ await fetch(`${BASE}/instances/${instId}/action`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ kind: "click",
+ ref: "e5"
+ })
+ });
+
+ // 5. Get text
+ const textResp = await fetch(`${BASE}/instances/${instId}/text`);
+ const text = await textResp.json();
+ console.log(`Page text: ${text.text.substring(0, 200)}...`);
+
+ // 6. Stop instance
+ await fetch(`${BASE}/instances/${instId}/stop`, {
+ method: "POST"
+ });
+ console.log(`Stopped instance: ${instId}`);
+
+ } catch (error) {
+ console.error("Error:", error);
+ }
}
main();
@@ -319,36 +384,44 @@ main();
## Configuration
-### Basic Configuration
+### Orchestrator Configuration
```bash
-# Custom port
+# Custom port (orchestrator)
BRIDGE_PORT=9868 pinchtab
-# Visible window
-BRIDGE_HEADLESS=false pinchtab
+# Auth token for remote access
+BRIDGE_TOKEN=my-secret-token pinchtab
-# Stealth mode (bypass bot detection)
-BRIDGE_STEALTH=full pinchtab
+# Bind to all interfaces (for remote access)
+BRIDGE_BIND=0.0.0.0 pinchtab
-# Block ads
-BRIDGE_BLOCK_ADS=true pinchtab
-
-# Custom Chrome
-CHROME_BINARY=/usr/bin/google-chrome pinchtab
+# Custom Chrome binary (used by all instances)
+CHROME_BIN=/usr/bin/google-chrome pinchtab
```
-### Combined
+### Instance Configuration
+
+Instance-specific options are set when creating instances:
```bash
-BRIDGE_PORT=9868 \
-BRIDGE_STEALTH=full \
-BRIDGE_BLOCK_ADS=true \
-BRIDGE_HEADLESS=false \
-pinchtab
+# Headless (default, fastest)
+pinchtab instance launch --mode headless
+
+# Headed (visible window, for debugging)
+pinchtab instance launch --mode headed
+
+# Specific port (usually auto-allocated)
+pinchtab instance launch --port 9999
+
+# With persistent profile
+pinchtab profile create work
+PROF_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="work") | .id')
+curl -X POST http://localhost:9867/instances/start \
+ -d '{"profileId":"'$PROF_ID'","mode":"headed"}'
```
-**[Full configuration β†’](architecture/pinchtab-architecture.md)**
+**[Full configuration β†’](references/configuration.md)**
---
@@ -357,88 +430,136 @@ pinchtab
### Scenario 1: Scrape a Website
```bash
+# Create instance
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
+
# Navigate
-pinchtab nav https://example.com/article
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com/article"}'
+
+# Extract text
+curl http://localhost:9867/instances/$INST/text | jq '.text'
-# Extract readable text
-pinchtab text > article.txt
+# Save to file
+curl http://localhost:9867/instances/$INST/text | jq -r '.text' > article.txt
-# Or with curl
-curl http://localhost:9867/text > article.json
-jq '.text' article.json
+# Stop instance
+curl -X POST http://localhost:9867/instances/$INST/stop
```
-### Scenario 2: Fill a Form
+### Scenario 2: Fill and Submit a Form
```bash
+# Create instance
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
+
# Navigate to form
-pinchtab nav https://example.com/contact
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com/contact"}'
-# Get interactive elements
-pinchtab snap -i -c
+# Get form structure
+SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)
-# Fill form fields (use refs from snapshot)
-pinchtab fill e3 "John Doe"
-pinchtab fill e5 "[email protected]"
-pinchtab fill e7 "My message here"
+# Fill fields (get refs from snapshot)
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e3","text":"John Doe"}'
+
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e5","text":"[email protected]"}'
+
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e7","text":"My message here"}'
# Click submit
-pinchtab click e10
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"e10"}'
# Verify success
-pinchtab snap
+curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | length'
```
### Scenario 3: Login + Stay Logged In
```bash
+# Create persistent profile
+pinchtab profile create mylogin
+PROF_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="mylogin") | .id')
+
+# Start instance with profile
+INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -d '{"profileId":"'$PROF_ID'"}' | jq -r '.id')
+sleep 2
+
# Login
-pinchtab nav https://example.com/login
-pinchtab fill e3 "[email protected]"
-pinchtab fill e5 "password"
-pinchtab click e7
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com/login"}'
-# Later, even after restarting PinchTab, you're still logged in
-pkill pinchtab
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e3","text":"[email protected]"}'
+
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e5","text":"password"}'
+
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"e7"}'
+
+# Stop instance (profile saved)
+curl -X POST http://localhost:9867/instances/$INST/stop
+
+# Later: restart with same profile (already logged in!)
+INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -d '{"profileId":"'$PROF_ID'"}' | jq -r '.id')
sleep 2
-pinchtab &
-# Tab and session restored (already authenticated)
-pinchtab nav https://example.com/dashboard
-pinchtab snap
+# Navigate to dashboard (cookies preserved)
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com/dashboard"}'
```
### Scenario 4: Generate PDF Report
```bash
-# Navigate to report page
-pinchtab nav https://reports.example.com/monthly
+# Create instance
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
-# Export as PDF with header/footer
-pinchtab pdf -o report.pdf \
- --landscape \
- --display-header-footer \
- --header-template "<div>Monthly Report</div>" \
- --footer-template "<div>Page <span class='pageNumber'></span></div>"
+# Navigate to report
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://reports.example.com/monthly"}'
+
+# Export PDF
+curl "http://localhost:9867/instances/$INST/pdf?landscape=true" -o report.pdf
```
### Scenario 5: Multi-Tab Workflow
```bash
-# Open first tab
-pinchtab nav https://source.example.com
-SOURCE_TAB=$(pinchtab tabs | jq -r '.[0].id')
+# Create instance
+INST=$(pinchtab instance launch | jq -r '.id')
+sleep 2
+
+# Open first tab (source)
+curl -X POST http://localhost:9867/tabs/open \
+ -d '{"instanceId":"'$INST'","url":"https://source.example.com"}'
-# Open second tab
-pinchtab tabs new https://destination.example.com
-DEST_TAB=$(pinchtab tabs | jq -r '.[1].id')
+# Open second tab (destination)
+curl -X POST http://localhost:9867/tabs/open \
+ -d '{"instanceId":"'$INST'","url":"https://destination.example.com"}'
-# Extract from source
-DATA=$(curl "http://localhost:9867/text?tabId=$SOURCE_TAB")
+# List tabs
+TABS=$(curl http://localhost:9867/instances/$INST/tabs)
+SOURCE_TAB=$(echo "$TABS" | jq -r '.[0].id')
+DEST_TAB=$(echo "$TABS" | jq -r '.[1].id')
-# Fill in destination
-curl -X POST http://localhost:9867/action \
- -d "{\"kind\":\"fill\",\"ref\":\"e3\",\"text\":\"$DATA\",\"tabId\":\"$DEST_TAB\"}"
+# Extract from source tab
+DATA=$(curl "http://localhost:9867/instances/$INST/text" | jq -r '.text')
+
+# Fill destination tab
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"fill","ref":"e3","text":"'$DATA'","tabId":"'$DEST_TAB'"}'
```
---
@@ -447,29 +568,50 @@ curl -X POST http://localhost:9867/action \
### "connection refused" / "Cannot connect"
-**Problem:** Server not running
+**Problem:** Orchestrator not running
**Solution:**
```bash
-# Terminal 1: Start server
+# Terminal 1: Start orchestrator
pinchtab
-# Terminal 2: Use client (once server is running)
-pinchtab snap
+# Terminal 2: Check health (once running)
+curl http://localhost:9867/health
+```
+
+### "Instance stuck in 'starting' state"
+
+**Problem:** Chrome takes time to initialize (8-20 seconds)
+
+**Solution:**
+```bash
+# Poll instance status
+INST=$(pinchtab instance launch | jq -r '.id')
+
+# Wait until 'running'
+while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" != "running" ]; do
+ sleep 0.5
+done
+
+# Now safe to use
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
```
### "Port already in use"
-**Problem:** Port 9867 is taken
+**Problem:** Port 9867 (or instance port) is taken
**Solution:**
```bash
-# Use different port
+# Use different orchestrator port
BRIDGE_PORT=9868 pinchtab
# Or kill the process using 9867
lsof -i :9867
kill -9 <PID>
+
+# Instance ports auto-allocated from 9868-9968, no manual config needed
```
### "Chrome not found"
@@ -485,33 +627,40 @@ brew install chromium
sudo apt install chromium-browser
# Or specify custom Chrome
-CHROME_BINARY=/path/to/chrome pinchtab
+CHROME_BIN=/path/to/chrome pinchtab
```
-### "Empty snapshot / about:blank"
+### "Empty snapshot / 404 error"
-**Problem:** Tab not navigated yet
+**Problem:** Instance ID is invalid or instance was stopped
**Solution:**
```bash
-# Always navigate first
-pinchtab nav https://example.com
+# List running instances
+curl http://localhost:9867/instances
-# Then snapshot
-pinchtab snap
+# Use valid instance ID
+INST=$(pinchtab instance launch | jq -r '.id')
+
+# Verify it's running
+curl http://localhost:9867/instances/$INST
```
### "ref e5 not found"
-**Problem:** Ref changed (page updated)
+**Problem:** Page updated or different page loaded
**Solution:**
```bash
# Get fresh snapshot
-pinchtab snap -i -c
+SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)
+
+# Extract new ref from snapshot
+NEW_REF=$(echo "$SNAP" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)
-# Use new refs from this snapshot
-pinchtab click <new-ref>
+# Use new ref
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"'$NEW_REF'"}'
```
---
@@ -543,59 +692,60 @@ pinchtab click <new-ref>
### Extract Text Efficiently
```bash
-# Readable text (strips ads, nav)
-pinchtab text # 800 tokens
-
-# Raw text (full page)
-pinchtab text --raw # ~1,500 tokens
+# Get text content
+curl http://localhost:9867/instances/$INST/text
-# Filter by selector
-pinchtab snap -s "main" # Only <main> element
+# Get snapshot (DOM structure)
+curl http://localhost:9867/instances/$INST/snapshot
-# Limit tokens
-pinchtab snap --max-tokens 1000
+# Filter snapshot to interactive elements
+curl http://localhost:9867/instances/$INST/snapshot | \
+ jq '.nodes[] | select(.role | IN("button", "link", "textbox"))'
```
-### Interact Precisely
+### Interact with Page
```bash
-# Get clickable elements only
-pinchtab snap -i
-
-# Click by ref
-pinchtab click e5
+# Click element
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"click","ref":"e5"}'
# Type text
-pinchtab type e3 "hello"
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"type","ref":"e3","text":"hello"}'
+
+# Fill input
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"fill","ref":"e3","text":"value"}'
-# Press keys
-pinchtab press Enter
-pinchtab press Tab
-pinchtab press Escape
+# Press key
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"press","key":"Enter"}'
# Focus element
-pinchtab focus e5
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"focus","ref":"e5"}'
-# Hover over element
-pinchtab hover e5
+# Hover element
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"hover","ref":"e5"}'
# Select dropdown
-pinchtab select e8 "Option 2"
+curl -X POST http://localhost:9867/instances/$INST/action \
+ -d '{"kind":"select","ref":"e8","text":"Option 2"}'
```
### Run JavaScript
```bash
-# Get page title
-curl -X POST http://localhost:9867/execute \
+# Evaluate expression
+curl -X POST http://localhost:9867/instances/$INST/evaluate \
+ -H "Content-Type: application/json" \
-d '{"expression":"document.title"}'
-# Count links
-curl -X POST http://localhost:9867/execute \
- -d '{"expression":"document.querySelectorAll(\"a\").length"}'
-
-# Complex logic
-curl -X POST http://localhost:9867/execute \
+# Get page info
+curl -X POST http://localhost:9867/instances/$INST/evaluate \
+ -H "Content-Type: application/json" \
-d '{"expression":"JSON.stringify({title: document.title, url: location.href})"}'
```
@@ -603,33 +753,46 @@ curl -X POST http://localhost:9867/execute \
## Performance Tips
-### Token Efficiency
+### Use Headless for Speed
```bash
-# Use text, not screenshot
-pinchtab text # 800 tokens
-pinchtab screenshot # 10,000+ tokens
+# Headless (default, faster)
+pinchtab instance launch --mode headless
+
+# Headed (visible window, slower, better for debugging)
+pinchtab instance launch --mode headed
+```
+
+### Parallel Processing
-# Filter to interactive elements only
-pinchtab snap -i -c # ~1,000 tokens
-pinchtab snap # ~3,600 tokens
+```bash
+# Create multiple instances for concurrent work
+for i in 1 2 3 4 5; do
+ INST=$(pinchtab instance launch | jq -r '.id')
+ INSTANCES+=("$INST")
+done
-# Limit by tokens
-pinchtab snap --max-tokens 1000
+# Distribute work across instances (round-robin)
+for URL in "${URLS[@]}"; do
+ INST="${INSTANCES[$((INDEX % 5))]}"
+ curl -X POST "http://localhost:9867/instances/$INST/navigate" \
+ -d '{"url":"'$URL'"}' &
+ ((INDEX++))
+done
+wait
```
-### Speed
+### Token Efficiency
```bash
-# Parallel tabs for concurrent work
-pinchtab tabs new https://...
-pinchtab tabs new https://...
-# Process multiple tabs in parallel
+# Use text extraction (cheaper than screenshots)
+curl http://localhost:9867/instances/$INST/text # Lower tokens
+
+# Use snapshot (cheaper than screenshot)
+curl http://localhost:9867/instances/$INST/snapshot # Lower tokens
-# Cache responses when possible
-# Snapshot once, extract refs, then interact
-pinchtab snap > snapshot.json
-# Use refs from snapshot.json multiple times
+# Screenshots are expensive (JPG encoding)
+curl http://localhost:9867/instances/$INST/screenshot # Higher tokens
```
---
@@ -638,18 +801,20 @@ pinchtab snap > snapshot.json
| Task | Command |
|------|---------|
-| Start server | `pinchtab` |
+| Start orchestrator | `pinchtab` |
| Health check | `curl http://localhost:9867/health` |
-| Navigate | `pinchtab nav https://...` |
-| See structure | `pinchtab snap -i -c` |
-| Get text | `pinchtab text` |
-| Click element | `pinchtab click e5` |
-| Type text | `pinchtab type e3 "hello"` |
-| Screenshot | `pinchtab screenshot -o page.jpg` |
-| PDF export | `pinchtab pdf -o out.pdf` |
-| List tabs | `pinchtab tabs` |
-| New tab | `pinchtab tabs new https://...` |
-| Show help | `pinchtab help` |
+| Create instance | `INST=$(pinchtab instance launch \| jq -r '.id')` |
+| Navigate | `curl -X POST http://localhost:9867/instances/$INST/navigate -d '{"url":"..."}' ` |
+| See structure | `curl http://localhost:9867/instances/$INST/snapshot` |
+| Get text | `curl http://localhost:9867/instances/$INST/text` |
+| Click element | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"click","ref":"e5"}'` |
+| Type text | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"type","ref":"e3","text":"hello"}'` |
+| Screenshot | `curl http://localhost:9867/instances/$INST/screenshot -o page.png` |
+| PDF export | `curl http://localhost:9867/instances/$INST/pdf -o out.pdf` |
+| List instances | `curl http://localhost:9867/instances` |
+| List tabs | `curl http://localhost:9867/instances/$INST/tabs` |
+| New tab | `curl -X POST http://localhost:9867/tabs/open -d '{"instanceId":"$INST","url":"..."}'` |
+| Stop instance | `curl -X POST http://localhost:9867/instances/$INST/stop` |
---
@@ -664,8 +829,10 @@ pinchtab snap > snapshot.json
## What's Next?
1. βœ… You've installed and run PinchTab
-2. πŸ“š Learn more β†’ [Full documentation](overview.md)
+2. πŸ“š Learn core concepts β†’ [Core Concepts](core-concepts.md)
3. 🎯 Try workflows β†’ [Practical examples](showcase.md)
-4. πŸ”§ Go deeper β†’ [Architecture docs](architecture/)
+4. πŸ”§ Learn instances β†’ [Instance API Reference](references/instance-api.md)
+5. πŸ“– Full API guide β†’ [curl-commands.md](references/curl-commands.md)
+6. πŸ—οΈ Deep dive β†’ [Architecture docs](architecture/pinchtab-architecture.md)
**Happy automating!** πŸ¦€