Skip to content

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.md
index 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 runtime
diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.md
index 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
-# Navigate
curl -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"
-# Click
curl -X POST http://localhost:9867/action \
-H 'Content-Type: application/json' \
-d '{"kind": "click", "ref": "e5"}'
-# Type
curl -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.md
index 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 tree
curl /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 ref
curl -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/ads
curl /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 JSON
curl /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.jpg
curl "/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 tabs
curl /tabs
diff --git a/tests/TEST-PLAN.md b/tests/TEST-PLAN.md
index 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 |
|---|----------|-------|----------|