High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add CLI examples to skill, README, API reference, and test plan
Marioa630393f13e7
diff --git a/README.md b/README.mdindex 3cf04805..18452a0a 100644--- a/README.md+++ b/README.md@@ -268,6 +268,34 @@ In headed mode, log into sites in the visible Chrome window once; cookies and lo| `tabId` | Target tab (default: first tab) || `mode=raw` | Raw `innerText` instead of readability extraction |+## CLI++The same `pinchtab` binary doubles as a CLI client. Start the server, then use subcommands:++```bash+pinchtab nav https://example.com # Navigate+pinchtab snap -i -c # Snapshot (interactive, compact)+pinchtab click e5 # Click element by ref+pinchtab type e12 hello world # Type into element+pinchtab press Enter # Press key+pinchtab text # Extract readable text+pinchtab ss -o page.jpg # Screenshot+pinchtab eval "document.title" # Run JavaScript+pinchtab pdf -o page.pdf --landscape # Export PDF+pinchtab tabs # List tabs+pinchtab tabs new https://example.com # Open new tab+pinchtab health # Check server+```++Short aliases: `nav`, `snap`, `ss`, `eval`, `tab`. Config via `PINCHTAB_URL` and `PINCHTAB_TOKEN` env vars. Pipe output with `jq`:++```bash+pinchtab text | jq .text+pinchtab snap -i -c | jq '.[] | select(.name | contains("Login"))'+```++Full help: `pinchtab help`+## Configuration### Core runtimediff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.mdindex d674f67d..dbde1ff0 100644--- a/skill/pinchtab/SKILL.md+++ b/skill/pinchtab/SKILL.md@@ -59,28 +59,35 @@ The typical agent loop:Refs (e.g. `e0`, `e5`, `e12`) are cached per tab after each snapshot — no need to re-snapshot before every action unless the page changed significantly.-### Quick examples+### Quick examples (CLI)++```bash+pinchtab nav https://example.com+pinchtab snap -i -c # interactive + compact+pinchtab click e5+pinchtab type e12 hello world+pinchtab press Enter+pinchtab text # readable text (~1K tokens)+pinchtab text | jq .text # pipe to jq+```++### Quick examples (curl)```bash-# Navigatecurl -X POST http://localhost:9867/navigate \-H 'Content-Type: application/json' \-d '{"url": "https://example.com"}'-# Snapshot (interactive only, compact format — best token efficiency)curl "http://localhost:9867/snapshot?filter=interactive&format=compact"-# Clickcurl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "click", "ref": "e5"}'-# Typecurl -X POST http://localhost:9867/action \-H 'Content-Type: application/json' \-d '{"kind": "type", "ref": "e12", "text": "hello world"}'-# Extract readable text (cheapest — ~1K tokens)curl http://localhost:9867/text```diff --git a/skill/pinchtab/references/api.md b/skill/pinchtab/references/api.mdindex ea6e1aba..807b5025 100644--- a/skill/pinchtab/references/api.md+++ b/skill/pinchtab/references/api.md@@ -2,9 +2,12 @@Base URL for all examples: `http://localhost:9867`+> **CLI alternative:** All endpoints have CLI equivalents. Use `pinchtab help` for the full list. Examples are shown as `# CLI:` comments below.+## Navigate```bash+# CLI: pinchtab nav https://example.com [--new-tab] [--block-images]curl -X POST /navigate \-H 'Content-Type: application/json' \-d '{"url": "https://example.com"}'@@ -18,6 +21,7 @@ curl -X POST /navigate \## Snapshot (accessibility tree)```bash+# CLI: pinchtab snap [-i] [-c] [-d] [-s main] [--max-tokens 2000]# Full treecurl /snapshot@@ -62,6 +66,7 @@ Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `## Act on elements```bash+# CLI: pinchtab click e5 / pinchtab type e12 hello / pinchtab press Enter# Click by refcurl -X POST /action -H 'Content-Type: application/json' \-d '{"kind": "click", "ref": "e5"}'@@ -120,6 +125,7 @@ curl -X POST /actions -H 'Content-Type: application/json' \## Extract text```bash+# CLI: pinchtab text [--raw]# Readability mode (default) — strips nav/footer/adscurl /text@@ -132,6 +138,7 @@ Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).## PDF export```bash+# CLI: pinchtab pdf [-o file.pdf] [--landscape] [--scale 0.8]# Returns base64 JSONcurl /pdf@@ -177,6 +184,7 @@ Sets files on `<input type=file>` elements via CDP. Fires `change` events. Selec## Screenshot```bash+# CLI: pinchtab ss [-o file.jpg] [-q 80]curl "/screenshot?raw=true" -o screenshot.jpgcurl "/screenshot?raw=true&quality=50" -o screenshot.jpg```@@ -184,6 +192,7 @@ curl "/screenshot?raw=true&quality=50" -o screenshot.jpg## Evaluate JavaScript```bash+# CLI: pinchtab eval "document.title"curl -X POST /evaluate -H 'Content-Type: application/json' \-d '{"expression": "document.title"}'```@@ -191,6 +200,7 @@ curl -X POST /evaluate -H 'Content-Type: application/json' \## Tab management```bash+# CLI: pinchtab tabs / pinchtab tabs new <url> / pinchtab tabs close <id># List tabscurl /tabsdiff --git a/tests/TEST-PLAN.md b/tests/TEST-PLAN.mdindex 4a96d349..581708c2 100644--- a/tests/TEST-PLAN.md+++ b/tests/TEST-PLAN.md@@ -179,7 +179,30 @@ Navigate to the test page first: `POST /navigate {"url":"file://<repo>/tests/ass| CF4 | Custom profile dir | `BRIDGE_PROFILE=/tmp/test-profile ./pinchtab` | Uses specified profile || CF5 | No restore | `BRIDGE_NO_RESTORE=true ./pinchtab` | Doesn't restore previous tabs |-### 1.14 Session Persistence+### 1.14 CLI Subcommands++| # | Scenario | Steps | Expected |+|---|----------|-------|----------|+| CL1 | Navigate | `pinchtab nav https://example.com` | JSON with title and url |+| CL2 | Snapshot interactive | `pinchtab snap -i -c` | Compact output, interactive elements only |+| CL3 | Snapshot diff | `pinchtab snap -d` | Only changes since last snapshot |+| CL4 | Click | `pinchtab click e5` | Action success |+| CL5 | Type | `pinchtab type e12 hello world` | Text typed into element |+| CL6 | Press | `pinchtab press Enter` | Key pressed |+| CL7 | Text extract | `pinchtab text` | JSON with url, title, text |+| CL8 | Text raw | `pinchtab text --raw` | Raw innerText |+| CL9 | Screenshot | `pinchtab ss -o /tmp/test.jpg` | File saved, size reported |+| CL10 | Evaluate | `pinchtab eval "document.title"` | Returns page title |+| CL11 | PDF | `pinchtab pdf -o /tmp/test.pdf` | PDF file saved |+| CL12 | Tabs list | `pinchtab tabs` | JSON array of tabs |+| CL13 | Tab new | `pinchtab tabs new https://example.com` | New tab opened |+| CL14 | Health | `pinchtab health` | JSON with status ok |+| CL15 | Help | `pinchtab help` | Help text with all commands |+| CL16 | Custom URL | `PINCHTAB_URL=http://localhost:9877 pinchtab health` | Connects to custom URL |+| CL17 | Auth token | `PINCHTAB_TOKEN=secret pinchtab health` (server has BRIDGE_TOKEN=secret) | Auth succeeds |+| CL18 | Server down | `pinchtab health` (no server running) | Error: connection failed |++### 1.15 Session Persistence| # | Scenario | Steps | Expected ||---|----------|-------|----------|