Skip to content

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

docs: documentation update (#361)

luigiagent15bfffbab230
diff --git a/README.md b/README.md
index ccf306ab..00ce7645 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,10 @@ pinchtab daemon install
This installs the control-plane server and starts a default headless Chrome instance, ready to accept requests from agents or manual API calls.
+PinchTab is designed first for local, single-user control on a machine you manage. Remote and distributed layouts are supported, but they are advanced operator-managed deployments. If you bind beyond loopback, publish ports, or attach remote bridges, you are responsible for tokens, network boundaries, TLS or reverse proxying, and which endpoint families you expose.
+
+If you run PinchTab on a different machine, do it only when you understand the security model. Keep it on a private or otherwise closed network, avoid exposing it directly to the public internet, and keep high-risk endpoint families disabled unless you explicitly need them. If you do enable them, lock them down so only the systems that need them can reach them.
+
If you prefer not to run a daemon, or if you're on Windows, you can instead run:
@@ -65,6 +69,8 @@ PinchTab defaults to a **local-first security posture**:
See the full guide: [docs/guides/security.md](docs/guides/security.md)
+Remote, container, and distributed setups are possible, but PinchTab is not positioned as a turnkey internet-facing browser service. Treat any non-local deployment as an advanced setup that you must secure explicitly.
+
## What can you use it for
### Headless navigation
@@ -165,6 +171,12 @@ brew install pinchtab/tap/pinchtab
npm install -g pinchtab
```
+### Platform Support
+
+PinchTab's primary tested operator workflow is local macOS and Linux.
+
+Windows binaries are published, but Windows support is currently limited and best-effort because the project does not have the same level of automated and manual coverage there. On Windows, prefer running `pinchtab server` or `pinchtab bridge` directly instead of relying on the daemon workflow.
+
### Shell Completion
Generate and install shell completions after `pinchtab` is on your `PATH`:
@@ -290,7 +302,7 @@ Read more in the [Core Concepts](https://pinchtab.com/docs/core-concepts) guide.
## Privacy
-PinchTab is a fully open-source, local-only tool. No telemetry, no analytics, no outbound connections. The binary binds to `127.0.0.1` by default. Persistent profiles store browser sessions locally on your machine — similar to how a human reuses their browser. The single Go binary (~16 MB) is fully verifiable: build from source at [github.com/pinchtab/pinchtab](https://github.com/pinchtab/pinchtab).
+PinchTab is a fully open-source, local-first tool. No telemetry, no analytics, and no required outbound service dependency. The binary binds to `127.0.0.1` by default. Persistent profiles store browser sessions locally on your machine, similar to how a human reuses their browser. Remote and distributed deployments are available for advanced use cases, but they are explicit operator-managed setups rather than the default posture. The single Go binary (~16 MB) is fully verifiable: build from source at [github.com/pinchtab/pinchtab](https://github.com/pinchtab/pinchtab).
---
diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.md
index 23c5743d..d530fe1a 100644
--- a/docs/architecture/mcp.md
+++ b/docs/architecture/mcp.md
@@ -35,7 +35,7 @@ pinchtab mcp
├── reads PINCHTAB_TOKEN (env or config)
│
├── creates internal/mcp.Client (HTTP client with 120 s timeout)
- ├── registers 21 MCP tools via mcp-go SDK
+ ├── registers 34 MCP tools via mcp-go SDK
└── calls server.ServeStdio() (blocking read loop)
```
@@ -46,7 +46,7 @@ The process exits when stdin is closed by the client.
```
internal/mcp/
├── server.go # NewServer() wires tools → handlers; Serve() starts stdio
-├── tools.go # allTools() — JSON-schema tool definitions for all 21 tools
+├── tools.go # allTools() — JSON-schema tool definitions for all 34 tools
├── handlers.go # handlerMap() — one handler closure per tool
└── client.go # Client — thin HTTP wrapper for PinchTab REST API
@@ -68,7 +68,7 @@ cmd/pinchtab/
- a human-readable description used by the LLM to select the right tool
- typed parameter schemas with `Required()` / `Description()` annotations
-The declarations are grouped by category: Navigation, Interaction, Content, Tab Management, Utility.
+The declarations are grouped by category: Navigation, Interaction, Keyboard, Content, Tab Management, Wait utilities, Network, and Dialog.
### handlers.go
@@ -95,10 +95,13 @@ The context passed from the MCP SDK carries the client's deadline, so long-runni
| Category | Count | REST Endpoints Used |
|----------|-------|---------------------|
| Navigation | 4 | `/navigate`, `/snapshot`, `/screenshot`, `/text` |
-| Interaction | 8 | `/action` (with `action` field) |
+| Interaction | 8 | `/action` |
+| Keyboard | 4 | `/action` |
| Content | 3 | `/evaluate`, `/pdf`, `/find` |
-| Tab Management | 4 | `/tabs`, `/health`, `/cookies` |
-| Utility | 2 | `/evaluate` (wait-for-selector), local sleep |
+| Tab Management | 5 | `/tabs`, `/health`, `/cookies`, `/profiles/{id}/instance` |
+| Wait utilities | 6 | `/wait` |
+| Network | 3 | `/network` |
+| Dialog | 1 | `/dialog` |
## Security Considerations
diff --git a/docs/commands.md b/docs/commands.md
index 6713a2d4..db854f35 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,157 +1,229 @@
# Commands Reference
-## Server & Daemon
+## Server And Runtime
-```
-pinchtab server # Start the full server (dashboard + API)
-pinchtab server --extension /path/to/ext # Start with extension (repeatable)
-pinchtab bridge # Start bridge-only server (no dashboard)
-pinchtab mcp # Start the MCP stdio server
-pinchtab daemon # Show daemon status
-pinchtab daemon install # Install as background service
-pinchtab daemon start # Start the background service
-pinchtab daemon stop # Stop the background service
-pinchtab daemon restart # Restart the background service
-pinchtab daemon uninstall # Remove the background service
+```bash
+pinchtab server # Start the full server (dashboard + API)
+pinchtab bridge # Start the bridge-only runtime
+pinchtab mcp # Start the MCP stdio server
+pinchtab daemon # Show daemon status
+pinchtab daemon install # Install as a background service
+pinchtab daemon start # Start the background service
+pinchtab daemon stop # Stop the background service
+pinchtab daemon restart # Restart the background service
+pinchtab daemon uninstall # Remove the background service
+pinchtab completion <shell> # Generate shell completions
```
## Navigation
-```
-pinchtab nav <url> # Navigate to URL in current tab
-pinchtab nav <url> --new-tab # Navigate in a new tab
-pinchtab nav <url> --tab <id> # Navigate a specific tab
-pinchtab nav <url> --block-images # Navigate with image blocking
-pinchtab nav <url> --block-ads # Navigate with ad blocking
-pinchtab quick <url> # Navigate + snapshot accessibility tree
-```
+`pinchtab nav <url>` uses `/navigate`. When you do not pass `--tab`, PinchTab opens a new tab and navigates it.
-```
-pinchtab back # Go back in browser history
-pinchtab back --tab <id> # Go back in specific tab
-pinchtab forward # Go forward in browser history
-pinchtab forward --tab <id> # Go forward in specific tab
-pinchtab reload # Reload current page
-pinchtab reload --tab <id> # Reload specific tab
+```bash
+pinchtab nav <url> # Open a new tab and navigate it
+pinchtab nav <url> --tab <id> # Reuse a specific tab
+pinchtab nav <url> --new-tab # Explicitly force a new tab
+pinchtab nav <url> --block-images # Block images for this navigation
+pinchtab nav <url> --block-ads # Block ads for this navigation
+pinchtab quick <url> # Navigate and take a snapshot
+pinchtab back # Go back in the active tab
+pinchtab back --tab <id> # Go back in a specific tab
+pinchtab forward # Go forward in the active tab
+pinchtab reload # Reload the active tab
```
Hidden aliases: `goto`, `navigate`, `open`
-## Tab Management
-
-```
-pinchtab tab # List all tabs
-pinchtab tab <id> # Focus tab by ID
-pinchtab tab new # Open a new empty tab
-pinchtab tab new <url> # Open a new tab with URL
-pinchtab tab close <id> # Close tab by ID
-```
-
-Alias: `tabs`
+## Tabs
-Numeric arguments are resolved as 1-based tab indices via `/tabs`. Non-numeric arguments are passed through as tab IDs.
-
-## Interaction
+The `tab` command only lists, focuses, creates, and closes tabs. It does not proxy the rest of the browser command set.
-```
-pinchtab click <ref> # Click element by ref
-pinchtab click --css <selector> # Click element by CSS selector
-pinchtab click --wait-nav <ref> # Click and wait for navigation
-pinchtab dblclick <ref> # Double-click element by ref
-pinchtab dblclick --css <selector> # Double-click element by CSS selector
-pinchtab type <ref> <text> # Type into element
-pinchtab fill <ref|selector> <text> # Fill input directly (no keystroke events)
-pinchtab press <key> # Press key (Enter, Tab, Escape...)
-pinchtab hover <ref> # Hover over element
-pinchtab hover --css <selector> # Hover by CSS selector
-pinchtab select <ref> <value> # Select dropdown option
-pinchtab check <selector> # Check a checkbox or radio
-pinchtab uncheck <selector> # Uncheck a checkbox or radio
-pinchtab scroll <ref|pixels> # Scroll to element or by pixel amount
+```bash
+pinchtab tab # List tabs
+pinchtab tab <id> # Focus a tab by ID or 1-based index
+pinchtab tab new # Open a blank tab
+pinchtab tab new <url> # Open a tab and navigate it
+pinchtab tab close <id> # Close a tab
```
-## Page Analysis
+Use top-level commands with `--tab` for tab-scoped work:
+```bash
+pinchtab snap --tab <id>
+pinchtab click --tab <id> <selector>
+pinchtab pdf --tab <id> -o page.pdf
```
-pinchtab snap # Snapshot accessibility tree
-pinchtab snap -i # Interactive elements only
-pinchtab snap -c # Compact output
-pinchtab snap -d # Diff from previous snapshot
-pinchtab snap --selector <css> # Scope to CSS selector
-pinchtab snap --max-tokens <n> # Limit token budget
-pinchtab snap --depth <n> # Limit tree depth
-pinchtab snap --text # Text output format
-pinchtab text # Extract page text (markdown)
-pinchtab text --raw # Raw text extraction
-pinchtab find <query> # Find elements by natural language
-pinchtab find --threshold <0-1> # Minimum similarity score
-pinchtab find --explain # Show score breakdown
-pinchtab find --ref-only # Output just the element ref
-pinchtab eval <expression> # Evaluate JavaScript
-```
-
-## Capture & Export
-```
-pinchtab screenshot # Take a screenshot (JPEG)
-pinchtab screenshot -o <path> # Save to specific path (format based on extension)
-pinchtab screenshot -q <0-100> # Set JPEG quality
-pinchtab pdf # Export page as PDF
-pinchtab pdf -o <path> # Save PDF to path
-pinchtab pdf --landscape # Landscape orientation
-pinchtab pdf --scale <n> # Page scale (e.g. 0.5)
-pinchtab pdf --paper-width <in> # Paper width in inches
-pinchtab pdf --paper-height <in> # Paper height in inches
-pinchtab pdf --page-ranges <r> # Page ranges (e.g. 1-3)
-pinchtab download <url> # Download a file
-pinchtab download <url> -o <path> # Download to specific path
-pinchtab upload <file> # Upload a file
-pinchtab upload <file> -s <css> # Upload to specific file input
-```
-
-## Instances & Profiles
-
-```
-pinchtab instances # List running instances
-pinchtab instance start # Start a new browser instance
-pinchtab instance start --profile <name> # Start with specific profile
-pinchtab instance start --port <n> # Start on specific port
-pinchtab instance start --extension /path/to/ext # Load extension (repeatable)
-pinchtab instance stop <id> # Stop an instance
-pinchtab instance logs <id> # View instance logs
-pinchtab instance navigate <id> <url> # Navigate instance to URL
-pinchtab profiles # List browser profiles
-pinchtab health # Check server health
-```
-
-## Configuration
+## Interaction
-```
-pinchtab config show # Show current configuration
-pinchtab config init # Create default config file
-pinchtab config path # Show config file path
-pinchtab config validate # Validate config file
-pinchtab config get <path> # Get a config value
-pinchtab config set <path> <val> # Set a config value
-pinchtab config patch <json> # Patch config with JSON
+Most element commands accept a unified selector:
+
+- snapshot ref such as `e5`
+- CSS selector such as `#login`
+- XPath such as `xpath://button`
+- text selector such as `text:Submit`
+- semantic selector such as `find:login button`
+
+```bash
+pinchtab click [selector] # Click an element or coordinates with --x/--y
+pinchtab click --css <selector> # Force CSS selector mode
+pinchtab click --wait-nav <selector> # Click and wait for navigation
+pinchtab dblclick [selector] # Double-click
+pinchtab type <selector> <text> # Type via key events
+pinchtab fill <selector> <text> # Fill directly
+pinchtab press <key> # Press a key
+pinchtab hover [selector] # Hover an element
+pinchtab focus [selector] # Focus an element
+pinchtab scroll <selector|pixels> # Scroll an element or the page
+pinchtab select <selector> <value> # Select a <select> option
+pinchtab check <selector> # Check a checkbox or radio
+pinchtab uncheck <selector> # Uncheck a checkbox or radio
+pinchtab scrollintoview <selector> # Scroll an element into view
```
-## Security
+## Page Analysis
-```
-pinchtab security # Review security posture
-pinchtab security up # Apply recommended security defaults
-pinchtab security down # Relax security settings
+```bash
+pinchtab snap # Accessibility snapshot
+pinchtab snap -i -c # Interactive + compact
+pinchtab snap -d # Diff from previous snapshot
+pinchtab snap --selector <css> # Scope snapshot
+pinchtab snap --max-tokens <n> # Limit token budget
+pinchtab snap --depth <n> # Limit tree depth
+pinchtab snap --text # Text output
+pinchtab text # Extract readable text
+pinchtab text --raw # Raw extraction
+pinchtab find <query> # Semantic element search
+pinchtab find --threshold <0-1> # Minimum similarity score
+pinchtab find --explain # Include score breakdown
+pinchtab find --ref-only # Print only the best ref
+pinchtab eval <expression> # Evaluate JavaScript
+```
+
+## Keyboard, Wait, And Diagnostics
+
+```bash
+pinchtab keyboard type <text> # Type at the focused element
+pinchtab keyboard inserttext <text> # Insert text without key events
+pinchtab keydown <key> # Hold a key down
+pinchtab keyup <key> # Release a key
+pinchtab wait <selector|ms> # Wait for selector or fixed duration
+pinchtab wait --text <text> # Wait for page text
+pinchtab wait --url <glob> # Wait for URL match
+pinchtab wait --load networkidle # Wait for load state
+pinchtab wait --fn <expression> # Wait for JS to become truthy
+pinchtab network # List captured network requests
+pinchtab network <requestId> # Show one request in detail
+pinchtab network --stream # Stream network entries
+pinchtab network --clear # Clear captured network data
+pinchtab dialog accept [text] # Accept alert/confirm/prompt
+pinchtab dialog dismiss # Dismiss dialog
+pinchtab console # Show console logs
+pinchtab console --clear # Clear console logs
+pinchtab errors # Show browser error logs
+pinchtab errors --clear # Clear browser error logs
+pinchtab clipboard read # Read server-side clipboard text
+pinchtab clipboard write <text> # Write clipboard text
+pinchtab clipboard copy <text> # Alias for write
+pinchtab clipboard paste # Alias for read
+```
+
+## Capture And Export
+
+```bash
+pinchtab screenshot # Save a screenshot to a generated .jpg path
+pinchtab screenshot -o <path> # Save screenshot to a chosen path
+pinchtab screenshot -q <0-100> # JPEG quality
+pinchtab pdf # Export the active page as PDF
+pinchtab pdf -o <path> # Save PDF to a chosen path
+pinchtab pdf --landscape # Landscape orientation
+pinchtab pdf --scale <n> # Print scale
+pinchtab pdf --paper-width <in> # Paper width in inches
+pinchtab pdf --paper-height <in> # Paper height in inches
+pinchtab pdf --page-ranges <r> # Page ranges such as 1-3
+pinchtab pdf --prefer-css-page-size # Use CSS page size
+pinchtab pdf --display-header-footer # Show header/footer
+pinchtab download <url> # Download through the browser session
+pinchtab download <url> -o <path> # Save downloaded file to a path
+pinchtab upload <file> # Upload to the default file input
+pinchtab upload <file> -s <css> # Upload to a specific file input
+```
+
+## Instances, Profiles, And Activity
+
+```bash
+pinchtab instances # List running instances
+pinchtab instance start # Start an instance
+pinchtab instance start --profile <id-or-name>
+pinchtab instance start --mode headed
+pinchtab instance start --port <n>
+pinchtab instance start --extension /path/to/ext
+pinchtab instance stop <id> # Stop an instance
+pinchtab instance logs <id> # Show instance logs
+pinchtab instance navigate <id> <url> # Open a tab in an instance and navigate it
+pinchtab profiles # List profiles
+pinchtab activity # List recorded activity events
+pinchtab activity tab <tab-id> # Filter activity by tab
+pinchtab health # Check server health
+```
+
+## Configuration And Security
+
+```bash
+pinchtab config # Interactive config overview/editor
+pinchtab config init # Create a default config file
+pinchtab config show # Print effective runtime config
+pinchtab config path # Print config file path
+pinchtab config validate # Validate the current config file
+pinchtab config get <path> # Read one file-config value
+pinchtab config set <path> <val> # Set one file-config value
+pinchtab config patch <json> # Merge JSON into the config file
+pinchtab security # Interactive security overview
+pinchtab security up # Apply stricter defaults
+pinchtab security down # Relax defaults
```
## Global Flags
-Most browser commands support `--tab <id>` to target a specific tab.
-
-Commands with `--tab`: nav, snap, click, dblclick, type, fill, press, hover, scroll, select, eval, screenshot, pdf, find, text
-
-```
-pinchtab <command> --tab <id> # Run command against specific tab
-pinchtab --help # Show help
-pinchtab --version # Show version
-```
+The root command supports:
+
+```bash
+pinchtab --server http://host:9867 <command>
+pinchtab --help
+pinchtab --version
+```
+
+Commands with `--tab` currently include:
+
+- `nav`
+- `back`
+- `forward`
+- `reload`
+- `snap`
+- `screenshot`
+- `pdf`
+- `find`
+- `text`
+- `click`
+- `dblclick`
+- `hover`
+- `focus`
+- `type`
+- `press`
+- `fill`
+- `scroll`
+- `select`
+- `eval`
+- `check`
+- `uncheck`
+- `keyboard type`
+- `keyboard inserttext`
+- `keydown`
+- `keyup`
+- `scrollintoview`
+- `network`
+- `wait`
+- `dialog accept`
+- `dialog dismiss`
+- `console`
+- `errors`
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
index e8a2aabc..2bf39e2c 100644
--- a/docs/core-concepts.md
+++ b/docs/core-concepts.md
@@ -132,7 +132,7 @@ curl -X POST http://localhost:9867/instances/start \
"mode": "headed"
}'
# CLI Alternative
-pinchtab instance start --profileId prof_278be873 --mode headed
+pinchtab instance start --profile prof_278be873 --mode headed
# Response
{
"id": "inst_0a89a5bb",
diff --git a/docs/dashboard.md b/docs/dashboard.md
index 39e86a9a..f569c431 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -96,7 +96,7 @@ curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
-d '{"profileId":"prof_278be873","mode":"headed"}'
# CLI Alternative
-pinchtab instance start --profileId prof_278be873 --mode headed
+pinchtab instance start --profile prof_278be873 --mode headed
# Response
{
"id": "inst_ea2e747f",
diff --git a/docs/endpoints.md b/docs/endpoints.md
index f1f1abb9..8e9d56ac 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -1,199 +1,356 @@
# Endpoints Reference
-## Health & Server
-
-```
-GET /health # Server health check (tab count, crash logs)
-POST /ensure-chrome # Force Chrome initialization
-GET /help # List all available endpoints
-GET /openapi.json # OpenAPI spec
-GET /metrics # Global metrics snapshot
-GET /welcome # Welcome HTML page
-POST /shutdown # Graceful server shutdown
-GET /api/events # SSE event stream (dashboard)
-```
-
-## Navigation
-
+This page lists the live HTTP surface exposed by PinchTab. Some routes are only available in bridge mode, some only in full server mode, and some are gated by security settings.
+
+## Health And Server Metadata
+
+```text
+GET /health
+POST /ensure-chrome
+GET /help
+GET /openapi.json
+GET /metrics
+GET /welcome
+POST /shutdown
+GET /api/events
```
-POST /navigate # Navigate current tab to URL
-GET /navigate?url=<url> # Navigate (GET variant)
-POST /tabs/{id}/navigate # Navigate a specific tab
-```
+Notes:
-Body: `{"url": "...", "timeout": 60, "blockImages": true, "newTab": true, "blockAds": true}`
+- in bridge mode, `/health` reports bridge health and tab count
+- in full server mode, `/health` reports dashboard health, auth state, and instance count
+- `/metrics` in full server mode is a server metrics snapshot, not the bridge memory view
-## History & Reload
+## Dashboard Auth And Config
+```text
+POST /api/auth/login
+POST /api/auth/elevate
+POST /api/auth/logout
+GET /api/config
+PUT /api/config
```
-POST /back # Go back in current tab
-POST /back?tabId=<id> # Go back in specific tab
-POST /tabs/{id}/back # Go back (tab-scoped)
-POST /forward # Go forward in current tab
-POST /forward?tabId=<id> # Go forward in specific tab
-POST /tabs/{id}/forward # Go forward (tab-scoped)
-POST /reload # Reload current tab
-POST /reload?tabId=<id> # Reload specific tab
-POST /tabs/{id}/reload # Reload (tab-scoped)
-```
-
-## Tab Management
-```
-GET /tabs # List all open tabs
-POST /tab # Tab actions: new, close, focus
-POST /tabs/{id}/close # Close a specific tab (orchestrator)
-GET /tabs/{id}/metrics # Per-tab metrics
+Notes:
+
+- `server.token` is treated as write-only by `PUT /api/config`
+- auth routes are for the dashboard session flow
+
+## Navigation And Tabs
+
+```text
+POST /navigate
+GET /navigate
+POST /tabs/{id}/navigate
+POST /back
+POST /back?tabId=<id>
+POST /tabs/{id}/back
+POST /forward
+POST /forward?tabId=<id>
+POST /tabs/{id}/forward
+POST /reload
+POST /reload?tabId=<id>
+POST /tabs/{id}/reload
+GET /tabs
+POST /tab
+POST /tabs/{id}/close
+GET /tabs/{id}/metrics
```
-Actions via `POST /tab`:
-- `{"action": "new", "url": "..."}` — open new tab
-- `{"action": "close", "tabId": "..."}` — close tab
-- `{"action": "focus", "tabId": "..."}` — focus/switch to tab
+Navigation request fields:
-## Tab Locking (multi-agent)
+- `url` required
+- `tabId` optional
+- `newTab` optional
+- `timeout` optional
+- `blockImages`, `blockMedia`, `blockAds` optional
+- `waitFor`, `waitSelector`, `waitTitle` optional
-```
-POST /tab/lock # Lock a tab {tabId, owner, timeoutSec}
-POST /tab/unlock # Unlock a tab {tabId, owner}
-POST /tabs/{id}/lock # Lock specific tab
-POST /tabs/{id}/unlock # Unlock specific tab
-```
+Important behavior:
-## Interaction
+- `POST /navigate` creates a new tab when `tabId` is omitted
+- `POST /tab` supports `new`, `close`, and `focus`
-```
-POST /action # Single action on current tab
-GET /action # Action (GET variant)
-POST /actions # Batch actions in sequence
-POST /macro # Multi-step macro with per-step timeout
-POST /tabs/{id}/action # Action on specific tab
-POST /tabs/{id}/actions # Batch actions on specific tab
-```
-
-Action kinds: `click`, `dblclick`, `type`, `fill`, `press`, `hover`, `scroll`, `select`, `focus`, `drag`, `check`, `uncheck`
-
-Body: `{"kind": "click", "ref": "e5"}` / `{"kind": "dblclick", "ref": "e5"}` / `{"kind": "type", "ref": "e12", "text": "hello"}` / `{"kind": "check", "selector": "#terms"}` / `{"kind": "uncheck", "ref": "e7"}`
-
-## Page Analysis
+## Tab Locking
+```text
+POST /tab/lock
+POST /tab/unlock
+POST /tabs/{id}/lock
+POST /tabs/{id}/unlock
```
-GET /snapshot # Accessibility tree (current tab)
-GET /tabs/{id}/snapshot # Accessibility tree (specific tab)
-GET /text # Extract readable text
-GET /tabs/{id}/text # Extract text (specific tab)
-POST /find # Semantic search in page
-POST /tabs/{id}/find # Semantic search (specific tab)
-POST /evaluate # Evaluate JavaScript
-POST /tabs/{id}/evaluate # Evaluate JS (specific tab)
-```
-
-Snapshot params: `?filter=interactive`, `?format=compact|text|yaml`, `?depth=5`, `?diff=true`, `?selector=main`, `?maxTokens=2000`, `?noAnimations=true`, `?output=file`
-
-Text params: `?mode=raw`, `?format=text`
-## Screenshot & PDF
-
-```
-GET /screenshot # Screenshot (current tab)
-GET /tabs/{id}/screenshot # Screenshot (specific tab)
-GET /pdf # PDF export (current tab)
-POST /pdf # PDF export with options
-GET /tabs/{id}/pdf # PDF export (specific tab)
-POST /tabs/{id}/pdf # PDF export with options (specific tab)
-GET /screencast # WebRTC screencast stream
-GET /screencast/tabs # All tabs screencast
+## Interaction And Analysis
+
+```text
+POST /action
+GET /action
+POST /actions
+POST /macro
+POST /tabs/{id}/action
+POST /tabs/{id}/actions
+GET /snapshot
+GET /tabs/{id}/snapshot
+GET /text
+GET /tabs/{id}/text
+POST /find
+POST /tabs/{id}/find
+POST /evaluate
+POST /tabs/{id}/evaluate
```
-Screenshot params: `?raw=true`, `?quality=80`
-
-PDF params: `?raw=true`, `?landscape=true`, `?scale=0.8`, `?pageRanges=1-5`, `?output=file`, `?path=/tmp/out.pdf`
-
-## Downloads & Uploads
-
-```
-GET /download # Download file via browser session
-GET /tabs/{id}/download # Download (specific tab)
-POST /upload # Upload file to input element
-POST /tabs/{id}/upload # Upload (specific tab)
-```
-
-Download params: `?url=<url>`, `?raw=true`, `?output=file`
-
-Upload body: `{"selector": "input[type=file]", "files": ["data:...base64..."]}`
-
-## Cookies
-
-```
-GET /cookies # Get cookies for current page
-POST /cookies # Set cookies
-GET /tabs/{id}/cookies # Get cookies (specific tab)
-POST /tabs/{id}/cookies # Set cookies (specific tab)
+Action kinds currently include:
+
+- `click`
+- `dblclick`
+- `type`
+- `fill`
+- `press`
+- `hover`
+- `focus`
+- `select`
+- `scroll`
+- `drag`
+- `check`
+- `uncheck`
+- `keyboard-type`
+- `keyboard-inserttext`
+- `keydown`
+- `keyup`
+- `scrollintoview`
+
+Action targeting fields:
+
+- `ref`
+- `selector`
+- `nodeId`
+- `x` and `y`
+
+Snapshot query parameters:
+
+- `interactive`
+- `compact`
+- `diff`
+- `selector`
+- `maxTokens`
+- `depth`
+- `format`
+- `noAnimations`
+- `output`
+
+Text query parameters:
+
+- `mode=raw`
+- `format`
+
+Find body fields:
+
+- `query`
+- `tabId`
+- `threshold`
+- `topK`
+- `lexicalWeight`
+- `embeddingWeight`
+- `explain`
+
+## Screenshot, PDF, And Screencast
+
+```text
+GET /screenshot
+GET /tabs/{id}/screenshot
+GET /pdf
+POST /pdf
+GET /tabs/{id}/pdf
+POST /tabs/{id}/pdf
+GET /screencast
+GET /screencast/tabs
+GET /instances/{id}/screencast
+GET /instances/{id}/proxy/screencast
```
-## Fingerprint
-
-```
-POST /fingerprint/rotate # Rotate browser fingerprint
+Screenshot query parameters:
+
+- `tabId`
+- `format=jpeg|png`
+- `quality`
+- `raw=true`
+- `output=file`
+- `noAnimations=true`
+
+PDF query parameters:
+
+- `tabId`
+- `raw=true`
+- `output=file`
+- `path`
+- `landscape`
+- `scale`
+- `paperWidth`
+- `paperHeight`
+- `marginTop`
+- `marginBottom`
+- `marginLeft`
+- `marginRight`
+- `pageRanges`
+- `preferCSSPageSize`
+- `displayHeaderFooter`
+- `headerTemplate`
+- `footerTemplate`
+- `generateTaggedPDF`
+- `generateDocumentOutline`
+
+## Downloads, Uploads, Cookies, And Clipboard
+
+```text
+GET /download
+GET /tabs/{id}/download
+POST /upload
+POST /tabs/{id}/upload
+GET /cookies
+POST /cookies
+GET /tabs/{id}/cookies
+POST /tabs/{id}/cookies
+GET /clipboard/read
+POST /clipboard/write
+POST /clipboard/copy
+GET /clipboard/paste
```
-## Instances (multi-instance)
-
+Notes:
+
+- download and upload endpoints are gated by `security.allowDownload` and `security.allowUpload`
+- clipboard endpoints are gated by `security.allowClipboard`
+- upload uses a JSON body with `selector` and `files`
+
+## Wait, Network, Dialog, Console, And Errors
+
+```text
+POST /wait
+POST /tabs/{id}/wait
+GET /network
+GET /network/stream
+GET /network/{requestId}
+POST /network/clear
+GET /tabs/{id}/network
+GET /tabs/{id}/network/stream
+GET /tabs/{id}/network/{requestId}
+POST /dialog
+POST /tabs/{id}/dialog
+GET /console
+POST /console/clear
+GET /errors
+POST /errors/clear
```
-GET /instances # List all instances
-GET /instances/{id} # Get instance details
-GET /instances/tabs # List tabs across all instances
-GET /instances/metrics # Metrics across all instances
-POST /instances/start # Start new instance
-POST /instances/launch # Launch by profile name
-POST /instances/attach # Attach external browser
-POST /instances/{id}/start # Start specific instance
-POST /instances/{id}/stop # Stop specific instance
-GET /instances/{id}/logs # Instance logs (ring buffer)
-GET /instances/{id}/logs/stream # Stream logs (SSE)
-GET /instances/{id}/tabs # List instance tabs
-POST /instances/{id}/tabs/open # Open tab in instance
-POST /instances/{id}/tab # Tab action proxied to instance
-```
-
-## Profiles
-```
-GET /profiles # List all profiles
-POST /profiles # Create profile
-POST /profiles/create # Create profile (alias)
-GET /profiles/{id} # Get profile details
-PATCH /profiles/{id} # Update profile
-DELETE /profiles/{id} # Delete profile
-POST /profiles/{id}/start # Start instance for profile
-POST /profiles/{id}/stop # Stop instance for profile
-GET /profiles/{id}/instance # Get profile's running instance
-POST /profiles/{id}/reset # Reset profile data
-GET /profiles/{id}/logs # Profile action logs
-GET /profiles/{id}/analytics # Profile analytics
-POST /profiles/import # Import profile from path
-PATCH /profiles/meta # Update profile metadata
+Wait body fields:
+
+- one of `selector`, `text`, `url`, `load`, `fn`, or `ms`
+- optional `tabId`
+- optional `timeout`
+- optional `state` for selector waits
+
+Network query parameters:
+
+- `tabId`
+- `filter`
+- `method`
+- `status`
+- `type`
+- `limit`
+- `bufferSize`
+- `body=true` on detail requests
+
+Dialog body fields:
+
+- `action`: `accept` or `dismiss`
+- `text`: optional prompt text
+- `tabId`: optional on `/dialog`
+
+Console and error routes use query parameters:
+
+- `tabId`
+- `limit`
+
+## Profiles And Instances
+
+```text
+GET /profiles
+POST /profiles
+POST /profiles/create
+GET /profiles/{id}
+PATCH /profiles/{id}
+DELETE /profiles/{id}
+POST /profiles/{id}/start
+POST /profiles/{id}/stop
+GET /profiles/{id}/instance
+POST /profiles/{id}/reset
+GET /profiles/{id}/logs
+GET /profiles/{id}/analytics
+POST /profiles/import
+PATCH /profiles/meta
+GET /instances
+GET /instances/{id}
+GET /instances/tabs
+GET /instances/metrics
+POST /instances/start
+POST /instances/launch
+POST /instances/attach
+POST /instances/attach-bridge
+POST /instances/{id}/start
+POST /instances/{id}/stop
+GET /instances/{id}/logs
+GET /instances/{id}/logs/stream
+GET /instances/{id}/tabs
+POST /instances/{id}/tabs/open
+POST /instances/{id}/tab
```
-## Scheduler
+Notes:
-```
-POST /tasks # Submit task to queue
-GET /tasks # List queued/running tasks
-GET /tasks/{id} # Get task status and result
-POST /tasks/{id}/cancel # Cancel a task
-POST /tasks/batch # Submit batch of tasks
-GET /scheduler/stats # Queue stats (depth, inflight, agents)
-```
+- `/instances/start` and `/instances/launch` use `mode`, not `headless`
+- `/profiles/{id}/start` uses `headless`
+- attach routes are gated by `security.attach`
-Task body: `{"agentId": "...", "action": "snapshot", "tabId": "..."}`
+## Activity And Scheduler
-## Config (Dashboard API)
-
-```
-GET /api/config # Get current configuration
-PUT /api/config # Update configuration
+```text
+GET /api/activity
+POST /tasks
+GET /tasks
+GET /tasks/{id}
+POST /tasks/{id}/cancel
+POST /tasks/batch
+GET /scheduler/stats
```
-`server.token` is write-only and managed outside the dashboard API via CLI or config file updates.
+Activity query parameters include:
+
+- `limit`
+- `ageSec`
+- `since`
+- `until`
+- `source`
+- `requestId`
+- `sessionId`
+- `actorId`
+- `agentId`
+- `instanceId`
+- `profileId`
+- `profileName`
+- `tabId`
+- `action`
+- `engine`
+- `pathPrefix`
+
+Scheduler routes are only present when `scheduler.enabled` is true.
+
+## Feature Gates
+
+Some endpoints are intentionally disabled unless the matching config allows them:
+
+- `/evaluate` and `/tabs/{id}/evaluate` -> `security.allowEvaluate`
+- `/download` and `/tabs/{id}/download` -> `security.allowDownload`
+- `/upload` and `/tabs/{id}/upload` -> `security.allowUpload`
+- clipboard routes -> `security.allowClipboard`
+- attach routes -> `security.attach`
+- screencast routes -> `security.allowScreencast`
diff --git a/docs/get-started.md b/docs/get-started.md
index 077af03c..da370b89 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -2,6 +2,8 @@
Get PinchTab running in a few minutes, from zero to browser automation.
+This guide covers the default local setup. If you plan to publish ports beyond localhost, bind to non-loopback interfaces, or run a remote or distributed topology, treat that as an advanced deployment and read the [Security guide](guides/security.md) first.
+
---
## Installation
@@ -34,7 +36,7 @@ pinchtab --version
**Requires:** Docker
```bash
-docker run -d -p 9867:9867 pinchtab/pinchtab
+docker run -d -p 127.0.0.1:9867:9867 pinchtab/pinchtab
curl http://localhost:9867/health
```
@@ -52,6 +54,12 @@ go build -o pinchtab ./cmd/pinchtab
**[Full build guide ->](architecture/building.md)**
+## Platform Support
+
+PinchTab's primary tested workflow is local macOS and Linux.
+
+Windows binaries are available, but Windows support is currently limited and best-effort because the project does not have the same level of test coverage there. On Windows, prefer direct runs with `pinchtab server` instead of expecting the full daemon workflow.
+
## Shell Completion
After installation, you can generate shell completions from the CLI:
@@ -81,7 +89,7 @@ The normal flow is:
### Step 1: start the server
```bash
-pinchtab
+pinchtab server
# Response
🦀 PinchTab port=9867
dashboard ready url=http://localhost:9867
@@ -155,14 +163,14 @@ curl http://localhost:9867/health
If that fails, start the server:
```bash
-pinchtab
+pinchtab server
```
### Port already in use
```bash
pinchtab config set server.port 9868
-pinchtab
+pinchtab server
```
### Chrome not found
@@ -175,7 +183,7 @@ brew install chromium
sudo apt install chromium-browser
# Custom Chrome binary (set in config)
-pinchtab config set browser.chromeBinary /path/to/chrome
+pinchtab config set browser.binary /path/to/chrome
```
---
diff --git a/docs/guides/daemon.md b/docs/guides/daemon.md
index a4368fc6..886fd2f9 100644
--- a/docs/guides/daemon.md
+++ b/docs/guides/daemon.md
@@ -1,6 +1,8 @@
# Background Service (Daemon)
-PinchTab can run as a user-level background service (daemon) on both macOS (`launchd`) and Linux (`systemd`). This ensures that the PinchTab server is always available to your agents without needing an open terminal window.
+PinchTab can run as a user-level background service (daemon) on macOS (`launchd`) and Linux (`systemd`). This ensures that the PinchTab server is always available to your agents without needing an open terminal window.
+
+This workflow is not currently provided on Windows. Windows binaries are available, but Windows support is limited and best-effort; on Windows, prefer running `pinchtab server` or `pinchtab bridge` directly.
![Daemon Status & Picker](../media/daemon-status.png)
diff --git a/docs/guides/data-storage.md b/docs/guides/data-storage.md
index d45a4ead..a2a0423c 100644
--- a/docs/guides/data-storage.md
+++ b/docs/guides/data-storage.md
@@ -107,7 +107,7 @@ Request activity is stored as one JSONL file per UTC day:
<server.stateDir>/activity/events-YYYY-MM-DD.jsonl
```
-By default PinchTab keeps one day of activity data and prunes older daily files when new activity is recorded. You can change that with:
+By default PinchTab keeps 1 day of activity data and prunes older daily files when new activity is recorded. You can change that with:
```json
{
diff --git a/docs/guides/identifying-instances.md b/docs/guides/identifying-instances.md
index 2dabee39..e9799686 100644
--- a/docs/guides/identifying-instances.md
+++ b/docs/guides/identifying-instances.md
@@ -16,8 +16,8 @@ cp "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" /usr/local/bin
chmod +x /usr/local/bin/pinchtab-chrome
# Set in config.json
-pinchtab config set browser.chromeBinary /usr/local/bin/pinchtab-chrome
-pinchtab
+pinchtab config set browser.binary /usr/local/bin/pinchtab-chrome
+pinchtab server
```
Now a process listing such as `ps -axo pid,command | rg pinchtab-chrome` gives you a quick way to spot the browser PinchTab launches.
@@ -73,7 +73,7 @@ curl http://localhost:9867/instances
For most setups, this combination is enough:
-1. point PinchTab to a renamed Chrome binary via `browser.chromeBinary` in config
+1. point PinchTab to a renamed Chrome binary via `browser.binary` in config
2. add a recognizable `browser.extraFlags` marker in config
3. verify the profile path or instance ID in the dashboard
@@ -81,6 +81,6 @@ For most setups, this combination is enough:
The same approach works in containers:
-- set `browser.chromeBinary` in config if you need to override the bundled browser path
+- set `browser.binary` in config if you need to override the bundled browser path
- put identifying flags in `browser.extraFlags`
- inspect the instance list from the API or dashboard rather than relying only on process names inside the container
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index 60c6a3de..a82b8bc7 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -12,7 +12,7 @@ PinchTab can run multiple isolated Chrome instances at the same time. Each runni
## Start The Orchestrator
```bash
-pinchtab
+pinchtab server
```
By default the orchestrator listens on `http://localhost:9867`.
@@ -81,7 +81,7 @@ curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
-d '{"profileId":"278be873adeb","mode":"headless"}'
# CLI Alternative
-pinchtab instance start --profileId 278be873adeb --mode headless
+pinchtab instance start --profile 278be873adeb --mode headless
```
Because a profile can have only one active managed instance, starting the same profile again while it is already active returns an error instead of creating a duplicate browser.
diff --git a/docs/guides/raspberry-pi.md b/docs/guides/raspberry-pi.md
index 13795a65..65161816 100644
--- a/docs/guides/raspberry-pi.md
+++ b/docs/guides/raspberry-pi.md
@@ -29,8 +29,8 @@ which chromium
If auto-detection misses it, set the binary path in config:
```bash
-pinchtab config set browser.chromeBinary /usr/bin/chromium-browser
-pinchtab
+pinchtab config set browser.binary /usr/bin/chromium-browser
+pinchtab server
```
## Install PinchTab
@@ -44,7 +44,7 @@ go build -o pinchtab ./cmd/pinchtab
Then start it:
```bash
-./pinchtab
+./pinchtab server
```
## Pi-Friendly Config
@@ -163,10 +163,10 @@ sudo systemctl status pinchtab
### Chrome Binary Not Found
-Set `browser.chromeBinary` in config:
+Set `browser.binary` in config:
```bash
-pinchtab config set browser.chromeBinary /usr/bin/chromium-browser
+pinchtab config set browser.binary /usr/bin/chromium-browser
```
### Out Of Memory
@@ -189,5 +189,5 @@ Change the port in config:
```bash
pinchtab config set server.port 9868
-./pinchtab
+./pinchtab server
```
diff --git a/docs/guides/remote-bridge-orchestrator.md b/docs/guides/remote-bridge-orchestrator.md
index afd18513..2ac0e156 100644
--- a/docs/guides/remote-bridge-orchestrator.md
+++ b/docs/guides/remote-bridge-orchestrator.md
@@ -6,6 +6,8 @@ Use this guide when:
- a PinchTab bridge server runs on another machine
- you want agents to keep talking to the orchestrator while the browser work happens remotely
+This is an advanced deployment pattern. Use it only when you understand the security model, keep the bridge on a private or otherwise closed network, and avoid exposing the bridge or orchestrator broadly beyond the systems that need to reach them. High-risk endpoint families should remain disabled unless they are explicitly required, and if enabled they should be reachable only by the minimum trusted systems involved in the deployment.
+
This is now a supported orchestration mode through:
```text
diff --git a/docs/guides/security.md b/docs/guides/security.md
index 18f61a25..b1f063eb 100644
--- a/docs/guides/security.md
+++ b/docs/guides/security.md
@@ -2,6 +2,10 @@
PinchTab is designed to be usable by default on a local machine without exposing high-risk browser control features unless you explicitly turn them on.
+PinchTab's default and primary deployment model is local-first: one user, one machine, one operator-controlled browser control plane. More complex topologies such as Docker, LAN access, remote bridges, or distributed orchestrator setups are supported, but they are advanced deployments. PinchTab should not be treated as a turnkey internet-facing service, and securing those deployments is the operator's responsibility.
+
+If you run PinchTab on a different machine, do so only if you understand the security model you are operating. Prefer a private or otherwise closed network, avoid exposing the service directly to the public internet, and keep high-risk capabilities disabled unless they are required for that deployment. If they must be enabled, restrict them so only the minimum trusted systems that need them can reach them.
+
The default security posture is:
- `server.bind = 127.0.0.1`
@@ -38,6 +42,20 @@ This means there are two independent questions:
Both matter.
+## Advanced Deployments
+
+If you intentionally run PinchTab beyond the default local setup, the minimum operator checklist is:
+
+- keep `server.token` set to a strong random value
+- narrow network reachability with a trusted network boundary, VPN, firewall, or reverse proxy
+- add TLS at the proxy or transport layer when traffic leaves the local machine
+- keep sensitive endpoint families disabled unless they are explicitly needed, and if they are enabled, restrict them to the minimum trusted callers or network paths that must reach them
+- scope `security.attach` and `security.idpi` deliberately for the remote topology you are operating
+
+Those choices are deployment responsibilities, not defaults that PinchTab can infer safely on your behalf.
+
+When the server is not running on the same machine as the user or agent, the bar should be higher: know which hosts can reach it, know which credentials protect it, know which endpoint families are enabled, and know which network boundary is containing it.
+
Binding to loopback reduces who can reach the API. Tokens reduce who can use it successfully. Sensitive endpoint gates reduce what a successful caller can do. IDPI reduces which websites and extracted content are trusted enough to pass deeper into an agent workflow.
## API Token
@@ -216,4 +234,4 @@ For a secure local setup:
}
```
-If you intentionally expose PinchTab beyond localhost, treat the token as mandatory and keep the sensitive endpoint families disabled unless you have a specific reason to enable them.
+If you intentionally expose PinchTab beyond localhost, treat the token as mandatory and keep the sensitive endpoint families disabled unless you have a specific reason to enable them. For anything more exposed than a single-machine local setup, assume you are operating an advanced deployment and review each security control explicitly.
diff --git a/docs/headless-vs-headed.md b/docs/headless-vs-headed.md
index c92ed48d..f6962330 100644
--- a/docs/headless-vs-headed.md
+++ b/docs/headless-vs-headed.md
@@ -128,7 +128,7 @@ curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
-d '{"profileId":"prof_278be873","mode":"headed"}'
# CLI Alternative
-pinchtab instance start --profileId prof_278be873 --mode headed
+pinchtab instance start --profile prof_278be873 --mode headed
# Response
{
"id": "inst_ea2e747f",
@@ -212,7 +212,9 @@ ssh -X user@server 'pinchtab instance start --mode headed'
### Windows
-Headed mode works with the native desktop session.
+Windows builds are available, but Windows support is currently limited and best-effort.
+Headed mode targets the native desktop session.
+Prefer direct local runs with `pinchtab server` or `pinchtab bridge`; the daemon workflow is not the primary Windows path.
### Docker
diff --git a/docs/mcp.md b/docs/mcp.md
index 14f7f168..2719002e 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1,29 +1,26 @@
# MCP Server
-PinchTab includes a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI agents control the browser directly through the standardized MCP interface.
+PinchTab includes a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI agents control the browser through MCP over stdio.
## Quick Start
-1. **Start PinchTab** in any mode (server or bridge):
+1. Start PinchTab in server or bridge mode:
```bash
pinchtab server
- #or
- pinchtab daemon install
+ # or
+ pinchtab bridge
```
-
-2. **Start the MCP server** (in a separate terminal or from your MCP client config):
+2. Start the MCP server in another terminal or from your MCP client config:
```bash
pinchtab mcp
```
-The MCP server communicates over **stdio** (stdin/stdout with JSON-RPC 2.0), which is the standard transport for MCP tools.
+The MCP server communicates over stdio using JSON-RPC, which is the standard MCP transport.
## Client Configuration
### Claude Desktop
-Add to your `claude_desktop_config.json`:
-
```json
{
"mcpServers": {
@@ -37,8 +34,6 @@ Add to your `claude_desktop_config.json`:
### VS Code / GitHub Copilot
-Create `.vscode/mcp.json` in your workspace:
-
```json
{
"servers": {
@@ -53,8 +48,6 @@ Create `.vscode/mcp.json` in your workspace:
### Cursor
-Add to your Cursor MCP settings:
-
```json
{
"mcpServers": {
@@ -66,284 +59,108 @@ Add to your Cursor MCP settings:
}
```
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PINCHTAB_TOKEN` | *(from config)* | Auth token for secured servers |
-
-For remote servers, use the `--server` flag: `pinchtab --server http://remote:9867 mcp`
-
-## Available Tools
-
-### Navigation (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `pinchtab_navigate` | Navigate to a URL |
-| `pinchtab_snapshot` | Get accessibility tree snapshot |
-| `pinchtab_screenshot` | Take a screenshot (base64 JPEG or PNG) |
-| `pinchtab_get_text` | Extract readable text content |
-
-### Interaction (8 tools)
-
-| Tool | Description |
-|------|-------------|
-| `pinchtab_click` | Click an element by ref |
-| `pinchtab_type` | Type text into an input |
-| `pinchtab_press` | Press a keyboard key |
-| `pinchtab_hover` | Hover over an element |
-| `pinchtab_focus` | Focus an element |
-| `pinchtab_select` | Select a dropdown option |
-| `pinchtab_scroll` | Scroll page or element |
-| `pinchtab_fill` | Fill input via JS dispatch |
-
-### Content (3 tools)
-
-| Tool | Description |
-|------|-------------|
-| `pinchtab_eval` | Execute JavaScript |
-| `pinchtab_pdf` | Export page as PDF |
-| `pinchtab_find` | Find elements by text or CSS |
-
-### Tab Management (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `pinchtab_list_tabs` | List open browser tabs |
-| `pinchtab_close_tab` | Close a tab |
-| `pinchtab_health` | Check server health |
-| `pinchtab_cookies` | Get page cookies |
-
-### Utility (2 tools)
-
-| Tool | Description |
-|------|-------------|
-| `pinchtab_wait` | Wait for N milliseconds |
-| `pinchtab_wait_for_selector` | Wait for a CSS selector to appear |
-
-## Tool Reference
-
-### pinchtab_navigate
-
-Navigate the browser to a URL.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `url` | string | Yes | URL to navigate to |
-| `tabId` | string | No | Target tab (uses current if empty) |
-
-### pinchtab_snapshot
-
-Get an accessibility tree snapshot of the page. This is the primary way agents understand page structure.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Target tab |
-| `interactive` | boolean | No | Only interactive elements |
-| `compact` | boolean | No | Compact format (fewer tokens) |
-| `diff` | boolean | No | Only changes since last snapshot |
-| `selector` | string | No | CSS selector to scope |
-
-### pinchtab_screenshot
-
-Capture a screenshot of the page. Defaults to JPEG.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Target tab |
-| `format` | string | No | `jpeg` (default) or `png` |
-| `quality` | number | No | JPEG quality 0-100 |
-
-### pinchtab_get_text
-
-Extract readable text from the page.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Target tab |
-| `raw` | boolean | No | Raw text without formatting |
-
-### pinchtab_click
-
-Click an element identified by its ref from a snapshot.
+## Environment
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Element ref (e.g., `e5`) |
-| `tabId` | string | No | Target tab |
+| Variable | Description |
+| --- | --- |
+| `PINCHTAB_TOKEN` | Auth token for secured servers |
-### pinchtab_type
+For remote servers, use the root `--server` flag:
-Type text into an input element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Element ref |
-| `text` | string | Yes | Text to type |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_press
-
-Press a keyboard key.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `key` | string | Yes | Key name (Enter, Tab, Escape, etc.) |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_hover
-
-Hover over an element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Element ref |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_focus
-
-Focus an element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Element ref |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_select
-
-Select a dropdown option.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Select element ref |
-| `value` | string | Yes | Option value |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_scroll
-
-Scroll the page or a specific element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | No | Element ref (omit for page scroll) |
-| `pixels` | number | No | Pixels to scroll (positive=down) |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_fill
-
-Fill an input using JavaScript dispatch (works with React/Vue/Angular).
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ref` | string | Yes | Element ref or CSS selector |
-| `value` | string | Yes | Value to fill |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_eval
-
-Execute JavaScript in the browser. Requires `security.allowEvaluate: true` in config.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `expression` | string | Yes | JavaScript expression |
-| `tabId` | string | No | Target tab |
-
-### pinchtab_pdf
-
-Export the page as a PDF document.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Target tab |
-| `landscape` | boolean | No | Landscape orientation |
-| `scale` | number | No | Print scale 0.1-2.0 |
-| `pageRanges` | string | No | Pages (e.g., "1-3,5") |
+```bash
+pinchtab --server http://remote:9867 mcp
+```
-### pinchtab_find
+## Available Tools
-Find elements by text content or CSS selector using semantic matching.
+PinchTab currently exposes 34 tools:
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | Yes | Text or CSS selector |
-| `tabId` | string | No | Target tab |
+- Navigation: 4
+- Interaction: 8
+- Keyboard: 4
+- Content: 3
+- Tab management: 5
+- Wait utilities: 6
+- Network: 3
+- Dialog: 1
-### pinchtab_list_tabs
+### Navigation
-List all open browser tabs. No parameters.
+- `pinchtab_navigate`
+- `pinchtab_snapshot`
+- `pinchtab_screenshot`
+- `pinchtab_get_text`
-### pinchtab_close_tab
+### Interaction
-Close a browser tab.
+- `pinchtab_click`
+- `pinchtab_type`
+- `pinchtab_press`
+- `pinchtab_hover`
+- `pinchtab_focus`
+- `pinchtab_select`
+- `pinchtab_scroll`
+- `pinchtab_fill`
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Tab to close (current if empty) |
+### Keyboard
-### pinchtab_health
+- `pinchtab_keyboard_type`
+- `pinchtab_keyboard_inserttext`
+- `pinchtab_keydown`
+- `pinchtab_keyup`
-Check server health. No parameters.
+### Content
-### pinchtab_cookies
+- `pinchtab_eval`
+- `pinchtab_pdf`
+- `pinchtab_find`
-Get cookies for the current page.
+### Tab Management
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tabId` | string | No | Target tab |
+- `pinchtab_list_tabs`
+- `pinchtab_close_tab`
+- `pinchtab_health`
+- `pinchtab_cookies`
+- `pinchtab_connect_profile`
-### pinchtab_wait
+### Wait Utilities
-Wait for a specified duration.
+- `pinchtab_wait`
+- `pinchtab_wait_for_selector`
+- `pinchtab_wait_for_text`
+- `pinchtab_wait_for_url`
+- `pinchtab_wait_for_load`
+- `pinchtab_wait_for_function`
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ms` | number | Yes | Milliseconds (max 30000) |
+### Network
-### pinchtab_wait_for_selector
+- `pinchtab_network`
+- `pinchtab_network_detail`
+- `pinchtab_network_clear`
-Wait for a CSS selector to appear on the page. Polls every 250ms.
+### Dialog
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `selector` | string | Yes | CSS selector |
-| `timeout` | number | No | Timeout ms (default 10000, max 30000) |
-| `tabId` | string | No | Target tab |
+- `pinchtab_dialog`
-## Typical Agent Workflow
+## Selector Model
-```
-1. pinchtab_navigate → go to URL
-2. pinchtab_snapshot → understand page structure
-3. pinchtab_click → interact with elements
-4. pinchtab_type → fill in forms
-5. pinchtab_snapshot → verify changes
-6. pinchtab_get_text → extract results
-```
+For selector-based interaction tools, prefer `selector`. `ref` is still accepted as a deprecated fallback on the element-action tools.
-## Architecture
+Common selector forms:
-The MCP server is a thin stdio-based JSON-RPC layer that translates MCP tool calls into HTTP requests to a running PinchTab instance:
+- `e5`
+- `#login`
+- `xpath://button`
+- `text:Submit`
+- `find:login button`
-```
-LLM Client ──stdio──▶ pinchtab mcp ──HTTP──▶ PinchTab Server
-```
+## Practical Flow
-This architecture means:
-- The MCP server works with any PinchTab deployment (local, remote, Docker)
-- No direct Chrome dependency — the server delegates to PinchTab
-- Built with [mcp-go](https://github.com/mark3labs/mcp-go) SDK (MCP spec 2025-11-25)
+The normal MCP browser loop is:
-## Code Layout
+1. `pinchtab_navigate`
+2. `pinchtab_snapshot`
+3. `pinchtab_click` / `pinchtab_type` / other action tools
+4. `pinchtab_wait_*` or `pinchtab_network` when needed
-```
-internal/mcp/
-├── server.go # MCP server setup and stdio transport
-├── tools.go # Tool definitions with JSON schemas
-├── handlers.go # Tool handler implementations
-└── client.go # HTTP client for PinchTab API
-
-cmd/pinchtab/
-└── cmd_mcp.go # `pinchtab mcp` subcommand
-```
+For full parameter details, see [MCP Tool Reference](./reference/mcp-tools.md).
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index f0853e70..8447c923 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -5,12 +5,11 @@
- interactive menu mode
- direct command mode
-Use menu mode when you want a guided local control surface.
-Use direct commands when you want a faster shell workflow or want to script PinchTab.
+Use the menu when you want a guided local control surface. Use direct commands when you want shell history, scripts, or remote targeting with `--server`.
## Interactive Menu
-When you run `pinchtab` with no subcommand in an interactive terminal, it shows the startup banner and main menu.
+Running `pinchtab` with no subcommand in an interactive terminal opens the menu. It does not immediately start the server.
Typical flow:
@@ -31,117 +30,97 @@ Main Menu
8. Exit
```
-What each entry does:
-
-- `Start server` starts the full PinchTab server
-- `Daemon` shows background service status and actions
-- `Start bridge` starts the single-instance bridge runtime
-- `Start MCP server` starts the stdio MCP server
-- `Config` opens the interactive config screen
-- `Security` opens the interactive security screen
-- `Help` shows the command help tree
-
## Direct Commands
-You can always bypass the menu and call commands directly.
-
-Common examples:
+Use direct commands when you already know the action you want:
```bash
pinchtab server
-pinchtab daemon
+pinchtab bridge
+pinchtab mcp
pinchtab config
-pinchtab security
pinchtab nav https://example.com
pinchtab snap -i -c
pinchtab click e5
-pinchtab text
+pinchtab find "login button"
+pinchtab network --limit 20
```
-Direct commands are the better fit when:
-
-- you are scripting PinchtTab
-- you want repeatable shell history
-- you are calling PinchtTab from another tool
-- you already know which command you want
-
-## Core Local Commands
-
-These are the main local-control commands surfaced in the menu:
+## Core Commands
| Command | Purpose |
| --- | --- |
-| `pinchtab` | Open the interactive menu in a terminal, or start the server in non-interactive use |
| `pinchtab server` | Start the full server and dashboard |
-| `pinchtab daemon` | Show daemon status and manage the background service |
-| `pinchtab config` | Open the interactive config overview/editor |
-| `pinchtab security` | Review or change the current security posture |
-| `pinchtab completion <shell>` | Generate shell completion scripts for `bash`, `zsh`, `fish`, or `powershell` |
| `pinchtab bridge` | Start the single-instance bridge runtime |
| `pinchtab mcp` | Start the stdio MCP server |
+| `pinchtab daemon` | Show daemon status and manage the background service |
+| `pinchtab config` | Open the interactive config overview/editor |
+| `pinchtab security` | Open the interactive security overview |
+| `pinchtab completion <shell>` | Generate shell completion scripts |
-## Shell Completion
+## Browser Commands
-Use the built-in completion command to generate shell-specific scripts:
+The browser control surface is top-level. `tab` is only for list/focus/new/close.
-```bash
-# Generate and install zsh completions
-pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+Common commands:
-# Generate bash completions
-pinchtab completion bash > /etc/bash_completion.d/pinchtab
+| Command | Purpose |
+| --- | --- |
+| `pinchtab nav <url>` | Open a new tab and navigate it |
+| `pinchtab quick <url>` | Navigate and snapshot |
+| `pinchtab snap` | Accessibility snapshot |
+| `pinchtab click <selector>` | Click an element |
+| `pinchtab type <selector> <text>` | Type via key events |
+| `pinchtab fill <selector> <text>` | Fill directly |
+| `pinchtab text` | Extract page text |
+| `pinchtab find <query>` | Semantic element search |
+| `pinchtab screenshot` | Save a screenshot |
+| `pinchtab pdf` | Export the page as PDF |
+| `pinchtab network` | Inspect captured network requests |
+| `pinchtab wait ...` | Wait for selector, text, URL, JS, or time |
+| `pinchtab console` | Show browser console logs |
+| `pinchtab errors` | Show browser error logs |
-# Generate fish completions
-pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
-```
+Many browser commands accept `--tab <id>` to target an existing tab instead of the active one.
-## Browser Shortcuts
+## Tab Command
-The most common browser control shortcuts are top-level commands:
+`pinchtab tab` is intentionally small:
-| Command | Purpose |
-| --- | --- |
-| `pinchtab nav <url>` | Navigate to a URL |
-| `pinchtab quick <url>` | Navigate and analyze the page |
-| `pinchtab snap` | Get an accessibility snapshot |
-| `pinchtab click <ref>` | Click an element ref |
-| `pinchtab type <ref> <text>` | Type into an element |
-| `pinchtab fill <ref|selector> <text>` | Fill an input directly |
-| `pinchtab text` | Extract page text |
-| `pinchtab screenshot` | Capture a screenshot |
-| `pinchtab pdf` | Export the current page as PDF |
-| `pinchtab health` | Check server health |
+```bash
+pinchtab tab
+pinchtab tab <id>
+pinchtab tab new [url]
+pinchtab tab close <id>
+```
-## Config From The CLI
+For tab-scoped actions, use the normal top-level command with `--tab`:
+
+```bash
+pinchtab click --tab <id> e5
+pinchtab pdf --tab <id> -o page.pdf
+```
-`pinchtab config` now acts as the main interactive config screen.
+## Config From The CLI
-It shows:
+`pinchtab config` shows:
-- instance strategy
-- allocation policy
-- default stealth level
-- default tab eviction policy
-- config file path
-- dashboard URL when the server is running
+- `multiInstance.strategy`
+- `multiInstance.allocationPolicy`
+- `instanceDefaults.stealthLevel`
+- `instanceDefaults.tabEvictionPolicy`
+- the active config file path
+- the dashboard URL when the server is running
- the masked server token
-- a `Copy token` action for clipboard/manual copy
+- a `Copy token` action
-For exact config commands and schema details, see [Config](./config.md).
+For file schema details and `config get/set/patch`, see [Config](./config.md).
## Security From The CLI
-`pinchtab security` is the main interactive security screen.
-
-Use it to:
+`pinchtab security` is the interactive security screen.
-- review the current posture
-- inspect warnings
-- edit individual security controls
-- apply `security up`
-- apply `security down`
-
-The direct subcommands also exist:
+Direct subcommands:
```bash
pinchtab security up
@@ -150,28 +129,23 @@ pinchtab security down
For broader security guidance, see [Security Guide](../guides/security.md).
-## Daemon From The CLI
-
-`pinchtab daemon` shows status, recent logs, and available actions.
+## Daemon
-The command is supported on:
+`pinchtab daemon` supports:
- macOS via `launchd`
- Linux via user `systemd`
-It will fail fast when the current environment cannot manage a user service, for example:
-
-- Linux shells without a working `systemctl --user` session
-- macOS sessions without an active GUI `launchd` domain
+Windows binaries exist, but daemon workflows are not currently supported there. Use `pinchtab server` or `pinchtab bridge` directly.
For operational details, see [Background Service (Daemon)](../guides/daemon.md).
## Full Command Tree
-Use the built-in help for the current command tree:
+Use built-in help for the live command tree:
```bash
pinchtab --help
```
-For per-command reference pages, start at [Reference Index](./index.md).
+For per-command pages, start at [Reference Index](./index.md).
diff --git a/docs/reference/click.md b/docs/reference/click.md
index cf302b55..883ed706 100644
--- a/docs/reference/click.md
+++ b/docs/reference/click.md
@@ -1,6 +1,6 @@
# Click
-Click an element by ref from a previous snapshot.
+Click an element using a snapshot ref, CSS selector, XPath selector, text selector, or semantic selector.
```bash
curl -X POST http://localhost:9867/action \
@@ -20,6 +20,8 @@ pinchtab click e5
Notes:
- element refs come from `/snapshot`
+- the raw action endpoint also accepts `selector`, for example `{"kind":"click","selector":"#login"}`
+- the CLI also accepts `#login`, `xpath://button`, `text:Submit`, and `find:login button`
- `--wait-nav` exists on the top-level CLI command
## Related Pages
diff --git a/docs/reference/config.md b/docs/reference/config.md
index 15071ee4..0928dcf2 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -2,8 +2,6 @@
`pinchtab config` is the CLI entry point for creating, inspecting, validating, and editing PinchTab's config file.
-Use this page as the command and schema reference. Broader deployment patterns can move to a separate guide later.
-
For security posture, token usage, sensitive endpoint policy, and IDPI guidance, see [Security](../guides/security.md).
## Commands
@@ -24,7 +22,7 @@ It also shows:
- the active config file path
- the dashboard URL when the server is running
- the masked server token
-- a `Copy token` action for clipboard/manual copy
+- a `Copy token` action
```bash
pinchtab config
@@ -32,24 +30,17 @@ pinchtab config
### `pinchtab config init`
-Creates a default config file at the standard user config location.
+Creates a default config file at the current config path.
```bash
pinchtab config init
```
-Current behavior note:
-
-- `config init` writes to the default config path
-- it does not currently switch to a custom `PINCHTAB_CONFIG` target path
+`config init` respects `PINCHTAB_CONFIG`. If that environment variable is set, the file is created there.
### `pinchtab config show`
-Shows the effective runtime configuration after applying:
-
-```text
-env vars -> config file -> built-in defaults
-```
+Shows the effective runtime configuration.
```bash
pinchtab config show
@@ -73,7 +64,7 @@ pinchtab config validate
### `pinchtab config get`
-Reads a single dotted-path value from the config file.
+Reads a single dotted-path value from the file config.
```bash
pinchtab config get server.port
@@ -83,7 +74,7 @@ pinchtab config get security.attach.allowHosts
### `pinchtab config set`
-Sets a single dotted-path value in the config file.
+Sets a single dotted-path value in the file config.
```bash
pinchtab config set server.port 8080
@@ -93,43 +84,42 @@ pinchtab config set multiInstance.strategy explicit
### `pinchtab config patch`
-Applies a JSON patch object to the config file.
+Merges a JSON object into the config file.
```bash
pinchtab config patch '{"server":{"port":"8080"}}'
pinchtab config patch '{"instanceDefaults":{"mode":"headed","maxTabs":50}}'
+pinchtab config patch '{"observability":{"activity":{"retentionDays":14}}}'
```
-## Config Priority
-
-PinchTab loads configuration in this order:
+## Load Order
-1. environment variables
-2. config file
-3. built-in defaults
+PinchTab applies configuration in this order:
-The supported env vars are:
+1. built-in defaults
+2. the config file selected by `PINCHTAB_CONFIG` or the default path
+3. `PINCHTAB_TOKEN`, if set, overriding `server.token` at runtime
-- `PINCHTAB_CONFIG` — path to config file
-- `PINCHTAB_TOKEN` — auth token (overrides config file)
+Supported environment variables:
-Everything else is configured in `config.json`. For CLI targeting a remote server, use the `--server` flag.
+- `PINCHTAB_CONFIG`: choose the config file path
+- `PINCHTAB_TOKEN`: override the API token at runtime
-For the common local workflow, prefer the interactive `pinchtab config` screen for everyday changes and use `get`, `set`, or `patch` when you need an exact scripted edit.
+For remote CLI targeting, use the root `--server` flag instead of config.
## Config File Location
Default location by OS:
- macOS: `~/Library/Application Support/pinchtab/config.json`
-- Linux: `~/.config/pinchtab/config.json` (respects `$XDG_CONFIG_HOME` if set)
+- Linux: `~/.config/pinchtab/config.json` or `$XDG_CONFIG_HOME/pinchtab/config.json`
- Windows: `%APPDATA%\pinchtab\config.json`
Legacy fallback:
- if `~/.pinchtab/config.json` exists and the newer location does not, PinchTab still uses the legacy location
-Override the read path with:
+Override the config path with:
```bash
export PINCHTAB_CONFIG=/path/to/config.json
@@ -137,40 +127,55 @@ export PINCHTAB_CONFIG=/path/to/config.json
## Config Shape
-Current nested config shape:
+Current nested file-config shape:
```json
{
+ "configVersion": "0.8.0",
"server": {
"port": "9867",
"bind": "127.0.0.1",
"token": "your-secret-token",
- "stateDir": "/path/to/state"
+ "stateDir": "/path/to/state",
+ "engine": "chrome",
+ "networkBufferSize": 100,
+ "trustProxyHeaders": false
},
"browser": {
"version": "144.0.7559.133",
"binary": "/path/to/chrome",
- "extraFlags": "",
+ "extraFlags": "--disable-gpu",
"extensionPaths": []
},
"instanceDefaults": {
"mode": "headless",
+ "noRestore": false,
+ "timezone": "Europe/Rome",
+ "blockImages": false,
+ "blockMedia": false,
+ "blockAds": false,
"maxTabs": 20,
"maxParallelTabs": 0,
+ "userAgent": "",
+ "noAnimations": false,
"stealthLevel": "light",
"tabEvictionPolicy": "close_lru",
- "blockAds": false,
- "blockImages": false,
- "blockMedia": false,
- "noRestore": false,
- "noAnimations": false
+ "dialogAutoAccept": false
},
"security": {
"allowEvaluate": false,
"allowMacro": false,
"allowScreencast": false,
"allowDownload": false,
+ "downloadAllowedDomains": [],
+ "downloadMaxBytes": 20971520,
"allowUpload": false,
+ "allowClipboard": false,
+ "uploadMaxRequestBytes": 10485760,
+ "uploadMaxFiles": 8,
+ "uploadMaxFileBytes": 5242880,
+ "uploadMaxTotalBytes": 10485760,
+ "maxRedirects": -1,
"attach": {
"enabled": false,
"allowHosts": ["127.0.0.1", "localhost", "::1"],
@@ -182,7 +187,8 @@ Current nested config shape:
"strictMode": true,
"scanContent": true,
"wrapContent": true,
- "customPatterns": []
+ "customPatterns": [],
+ "scanTimeoutSec": 5
}
},
"profiles": {
@@ -216,6 +222,13 @@ Current nested config shape:
"maxPerAgentInflight": 10,
"resultTTLSec": 300,
"workerCount": 4
+ },
+ "observability": {
+ "activity": {
+ "enabled": true,
+ "sessionIdleSec": 1800,
+ "retentionDays": 1
+ }
}
}
```
@@ -224,14 +237,40 @@ Current nested config shape:
| Section | Purpose |
| --- | --- |
-| `server` | HTTP server settings |
-| `browser` | Chrome executable and launch wiring |
+| `server` | HTTP server settings, engine selection, proxy trust, and network buffer defaults |
+| `browser` | Chrome executable, version pin, extra flags, and extension paths |
| `instanceDefaults` | Default behavior for managed instances |
-| `security` | Sensitive feature gates, attach policy, and IDPI |
+| `security` | Sensitive feature gates, transfer limits, attach policy, and IDPI |
| `profiles` | Profile storage defaults |
-| `multiInstance` | Strategy, allocation, instance port range, and restart policy |
-| `timeouts` | Runtime timeouts |
-| `scheduler` | Optional task queue (see [Scheduler](./scheduler.md)) |
+| `multiInstance` | Orchestrator strategy, allocation, port range, and restart policy |
+| `timeouts` | Action, navigation, shutdown, and navigation wait delays |
+| `scheduler` | Optional task queue |
+| `observability` | Activity logging and retention |
+
+## `config get` And `config set` Support
+
+`pinchtab config get` and `pinchtab config set` only support these top-level sections:
+
+- `server`
+- `browser`
+- `instanceDefaults`
+- `security`
+- `profiles`
+- `multiInstance`
+- `timeouts`
+
+They do not expose every field in those sections, and they do not support `scheduler.*` or `observability.*`.
+
+Use `pinchtab config patch` or edit `config.json` directly for fields such as:
+
+- `server.engine`
+- `server.networkBufferSize`
+- `browser.extensionPaths`
+- `instanceDefaults.dialogAutoAccept`
+- `security.allowClipboard`
+- `security.idpi.scanTimeoutSec`
+- `scheduler.*`
+- `observability.*`
## Common Examples
@@ -250,16 +289,13 @@ Current nested config shape:
```bash
pinchtab config set server.bind 0.0.0.0
pinchtab config set server.token secret
-pinchtab
+pinchtab server
```
### Custom Instance Port Range
```json
{
- "server": {
- "port": "8080"
- },
"multiInstance": {
"instancePortStart": 8100,
"instancePortEnd": 8200
@@ -267,17 +303,6 @@ pinchtab
}
```
-### Tab Eviction Policy
-
-```json
-{
- "instanceDefaults": {
- "maxTabs": 10,
- "tabEvictionPolicy": "close_lru"
- }
-}
-```
-
### Attach Policy
```json
@@ -286,31 +311,25 @@ pinchtab
"attach": {
"enabled": true,
"allowHosts": ["127.0.0.1", "localhost", "chrome.internal"],
- "allowSchemes": ["ws", "wss"]
+ "allowSchemes": ["ws", "wss", "http", "https"]
}
}
}
```
-### IDPI Policy
+### Activity Retention
```json
{
- "security": {
- "idpi": {
- "enabled": true,
- "allowedDomains": ["example.com", "*.example.com"],
- "strictMode": true,
- "scanContent": true,
- "wrapContent": true,
- "customPatterns": []
+ "observability": {
+ "activity": {
+ "retentionDays": 14,
+ "sessionIdleSec": 1800
}
}
}
```
-This is policy only. The actual `cdpUrl` is provided in the attach request, not in global config.
-
## Legacy Flat Format
Older flat config is still accepted for backward compatibility:
@@ -326,13 +345,12 @@ Older flat config is still accepted for backward compatibility:
}
```
-Use `pinchtab config init` to create a nested config file.
+Use `pinchtab config init` to create the current nested format.
## Validation
-`pinchtab config validate` currently checks, among other things:
+`pinchtab config validate` checks, among other things:
-- valid server port values
- valid `instanceDefaults.mode`
- valid `instanceDefaults.stealthLevel`
- valid `instanceDefaults.tabEvictionPolicy`
@@ -345,6 +363,9 @@ Use `pinchtab config init` to create a nested config file.
- `multiInstance.instancePortStart <= multiInstance.instancePortEnd`
- `multiInstance.restart.initBackoffSec <= multiInstance.restart.maxBackoffSec`
- non-negative timeout values
+- non-negative `server.networkBufferSize`
+- non-negative `security.idpi.scanTimeoutSec`
+- positive `observability.activity.sessionIdleSec` and `retentionDays`
Valid enum values:
@@ -352,13 +373,13 @@ Valid enum values:
| --- | --- |
| `instanceDefaults.mode` | `headless`, `headed` |
| `instanceDefaults.stealthLevel` | `light`, `medium`, `full` |
-| `instanceDefaults.tabEvictionPolicy` | `reject`, `close_oldest`, `close_lru` (default) |
-| `multiInstance.strategy` | `simple`, `explicit`, `simple-autorestart`, `always-on` (default), `no-instance` |
+| `instanceDefaults.tabEvictionPolicy` | `reject`, `close_oldest`, `close_lru` |
+| `multiInstance.strategy` | `simple`, `explicit`, `simple-autorestart`, `always-on`, `no-instance` |
| `multiInstance.allocationPolicy` | `fcfs`, `round_robin`, `random` |
| `security.attach.allowSchemes` | `ws`, `wss`, `http`, `https` |
## Notes
- `config show` reports effective runtime values, not just raw file contents.
-- `config get`, `set`, and `patch` operate on the file config model, not on transient env overrides.
-- Most operational behavior now belongs in `config.json`, not in startup env vars.
+- `config get`, `set`, and `patch` operate on the file config model, not transient runtime overrides.
+- the dashboard config API treats `server.token` as write-only; use the CLI or file editing to manage it.
diff --git a/docs/reference/fill.md b/docs/reference/fill.md
index 99b7d47c..d11e29be 100644
--- a/docs/reference/fill.md
+++ b/docs/reference/fill.md
@@ -19,8 +19,8 @@ pinchtab fill e8 "[email protected]"
Notes:
-- the top-level CLI also accepts a selector form: `pinchtab fill 'input[name=email]' "[email protected]"`
-- for the raw HTTP action endpoint, selectors use `selector`, not `ref`
+- the top-level CLI accepts unified selector forms such as `e8`, `#email`, or `text:Email`
+- for the raw HTTP action endpoint, use `selector` for CSS, XPath, text, or semantic selectors
## Related Pages
diff --git a/docs/reference/find.md b/docs/reference/find.md
index 7bb5fcb1..6b97e65e 100644
--- a/docs/reference/find.md
+++ b/docs/reference/find.md
@@ -6,7 +6,7 @@ It works against the accessibility snapshot for a tab and returns the best match
## Endpoints
-PinchTab currently exposes two useful forms:
+PinchTab exposes two forms:
- `POST /find`
- `POST /tabs/{id}/find`
@@ -33,27 +33,17 @@ Use `POST /tabs/{id}/find` when you already know the tab ID and want the orchest
curl -X POST http://localhost:9867/tabs/<tabId>/find \
-H "Content-Type: application/json" \
-d '{"query":"login button","threshold":0.3,"topK":3}'
-# Response
-{
- "best_ref": "e5",
- "confidence": "high",
- "score": 0.85,
- "matches": [
- {
- "ref": "e5",
- "score": 0.85,
- "role": "button",
- "name": "Log in"
- }
- ],
- "strategy": "combined:lexical+embedding:hashing",
- "threshold": 0.3,
- "latency_ms": 2,
- "element_count": 42
-}
+# CLI Alternative
+pinchtab find --tab <tabId> "login button"
```
-There is no dedicated CLI `find` command at the moment.
+There is a dedicated CLI `find` command:
+
+```bash
+pinchtab find "login button"
+pinchtab find --threshold 0.5 --explain "primary submit button"
+pinchtab find --ref-only "search input"
+```
## Using `POST /find`
@@ -61,24 +51,6 @@ There is no dedicated CLI `find` command at the moment.
curl -X POST http://localhost:9867/find \
-H "Content-Type: application/json" \
-d '{"tabId":"<tabId>","query":"search input"}'
-# Response
-{
- "best_ref": "e7",
- "confidence": "high",
- "score": 0.91,
- "matches": [
- {
- "ref": "e7",
- "score": 0.91,
- "role": "textbox",
- "name": "Search"
- }
- ],
- "strategy": "combined:lexical+embedding:hashing",
- "threshold": 0.3,
- "latency_ms": 18,
- "element_count": 142
-}
```
If `tabId` is omitted, PinchTab uses the active tab in the current bridge context.
@@ -95,12 +67,9 @@ If `tabId` is omitted, PinchTab uses the active tab in the current bridge contex
| `threshold` | Threshold used for the request |
| `latency_ms` | Matching time in milliseconds |
| `element_count` | Number of elements evaluated |
+| `idpiWarning` | Advisory warning when IDPI is in warn mode |
-When `explain` is enabled, each match may also include:
-
-- `lexical_score`
-- `embedding_score`
-- `composite`
+When `explain` is enabled, each match may also include lexical and embedding score details.
## Confidence Levels
@@ -124,12 +93,6 @@ Example:
curl -X POST http://localhost:9867/tabs/<tabId>/find \
-H "Content-Type: application/json" \
-d '{"query":"username input"}'
-# Response
-{
- "best_ref": "e14",
- "confidence": "high",
- "score": 0.85
-}
```
Then use the returned ref:
@@ -152,5 +115,6 @@ curl -X POST http://localhost:9867/tabs/<tabId>/action \
| Status | Condition |
| --- | --- |
| `400` | invalid JSON or missing `query` |
+| `403` | blocked by IDPI in strict mode |
| `404` | tab not found |
| `500` | Chrome not initialized, snapshot unavailable, or matcher failure |
diff --git a/docs/reference/focus.md b/docs/reference/focus.md
index 1887da0a..3c8c137b 100644
--- a/docs/reference/focus.md
+++ b/docs/reference/focus.md
@@ -1,6 +1,6 @@
# Focus
-Move focus to an element by ref.
+Move focus to an element by selector or ref.
```bash
curl -X POST http://localhost:9867/action \
@@ -19,6 +19,8 @@ pinchtab focus e8
This is useful before keyboard-only flows such as `press Enter` or `type`.
+The raw action endpoint accepts either `ref` or `selector`. The CLI accepts the same unified selector forms as other top-level action commands.
+
## Related Pages
- [Press](./press.md)
diff --git a/docs/reference/health.md b/docs/reference/health.md
index 49290814..6d8bfa36 100644
--- a/docs/reference/health.md
+++ b/docs/reference/health.md
@@ -15,13 +15,18 @@ pinchtab health
}
```
-Notes:
+Bridge-mode health may also include:
+
+- `crashLogs`
+- `failures`
+- `crashes`
-- returns tab count for the attached browser
-- in error cases returns `503` with `status: "error"`
+In error cases it returns `503` with `status: "error"` and a `reason`.
## Server Mode (Dashboard)
+In full server mode, `/health` returns the dashboard health envelope:
+
```bash
curl http://localhost:9867/health
# Response
@@ -30,6 +35,7 @@ curl http://localhost:9867/health
"mode": "dashboard",
"version": "0.8.0",
"uptime": 12345,
+ "authRequired": true,
"profiles": 1,
"instances": 1,
"defaultInstance": {
@@ -42,25 +48,24 @@ curl http://localhost:9867/health
```
| Field | Description |
-|-------|-------------|
+| --- | --- |
| `status` | `ok` when server is healthy |
-| `mode` | Always `dashboard` in server mode |
+| `mode` | `dashboard` in server mode |
| `version` | PinchTab version |
| `uptime` | Milliseconds since server start |
+| `authRequired` | `true` when a server token is configured |
| `profiles` | Number of configured profiles |
-| `instances` | Number of running browser instances |
-| `defaultInstance` | First managed instance info (if any) |
-| `defaultInstance.id` | Instance ID |
-| `defaultInstance.status` | `starting`, `running`, `stopping`, `stopped`, `error` |
-| `agents` | Number of connected agents |
-| `restartRequired` | True if config changes need restart |
-| `restartReasons` | List of reasons (when `restartRequired` is true) |
+| `instances` | Number of managed instances |
+| `defaultInstance` | First managed instance info, when present |
+| `agents` | Connected agent count |
+| `restartRequired` | `true` when file-based config changes need restart |
+| `restartReasons` | Restart reason list when required |
Notes:
-- `defaultInstance` is present when at least one instance is running
-- use `defaultInstance.status == "running"` to check Chrome is ready
-- strategies like `always-on` launch an instance at startup
+- `defaultInstance` is present when at least one instance exists
+- use `defaultInstance.status == "running"` when you want to confirm Chrome is ready
+- strategies such as `always-on` can create an instance automatically at startup
## Related Pages
diff --git a/docs/reference/hover.md b/docs/reference/hover.md
index 51c92631..03be62e1 100644
--- a/docs/reference/hover.md
+++ b/docs/reference/hover.md
@@ -1,6 +1,6 @@
# Hover
-Move the pointer over an element by ref.
+Move the pointer over an element by selector or ref.
```bash
curl -X POST http://localhost:9867/action \
@@ -19,6 +19,8 @@ pinchtab hover e5
Use this when menus or tooltips appear only after hover.
+The raw action endpoint accepts either `ref` or `selector`. The CLI accepts unified selector forms such as `e5`, `#menu`, `xpath://button`, `text:Menu`, and `find:account menu`.
+
## Related Pages
- [Click](./click.md)
diff --git a/docs/reference/instances.md b/docs/reference/instances.md
index 0dfeb2cf..163a8939 100644
--- a/docs/reference/instances.md
+++ b/docs/reference/instances.md
@@ -16,89 +16,61 @@ One profile can have at most one active managed instance at a time.
curl http://localhost:9867/instances
# CLI Alternative
pinchtab instances
-# Response
-[
- {
- "id": "inst_0a89a5bb",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9868",
- "headless": true,
- "status": "running",
- "startTime": "2026-03-01T05:21:38.27432Z"
- }
-]
```
`pinchtab instances` is the simplest way to inspect the current fleet from the CLI.
## Start An Instance
-### Primary: Start by profileId and mode
+### `POST /instances/start`
+
+Use `/instances/start` when you want to start by profile ID or profile name, or let PinchTab create a temporary profile.
```bash
curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
-d '{"profileId":"prof_278be873","mode":"headed","port":"9999"}'
# CLI Alternative
-pinchtab instance start --profileId prof_278be873 --mode headed --port 9999
-# Response
-{
- "id": "inst_ea2e747f",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9999",
- "headless": false,
- "status": "starting",
- "startTime": "2026-03-01T05:21:38.27432Z"
-}
+pinchtab instance start --profile prof_278be873 --mode headed --port 9999
```
+Request body:
+
+- `profileId`: optional; accepts a profile ID or an existing profile name
+- `mode`: optional; use `headed` for a visible browser, anything else is treated as headless
+- `port`: optional
+- `extensionPaths`: optional array of extension paths
+
Notes:
-- if `profileId` is omitted, PinchTab creates an auto-generated temporary profile such as `instance-...`
+- if `profileId` is omitted, PinchTab creates an auto-generated temporary profile
- if `port` is omitted, PinchTab allocates one from the configured instance port range
+- the CLI flag is `--profile`, even though the API field is `profileId`
-### Alternative: Start by profile name
+### `POST /instances/launch`
-You can also start an instance using a profile name and headless flag:
+Use `/instances/launch` when you want to launch by profile name or `profileId` through the compatibility route.
```bash
curl -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d '{"name":"work","headless":false}'
-# Response
-{
- "id": "inst_ea2e747f",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9999",
- "headless": false,
- "status": "starting",
- "startTime": "2026-03-01T05:21:38.27432Z"
-}
+ -d '{"name":"work","mode":"headed"}'
```
-The `POST /instances/launch` endpoint takes:
-- `name` — profile name (required)
-- `headless` — true for headless mode, false for headed mode (optional, defaults to true)
+Request body:
-Port is automatically allocated from the configured instance port range.
+- `name`: optional profile name
+- `profileId`: optional profile ID
+- `mode`: optional; `headed` or headless by default
+- `port`: optional
+- `extensionPaths`: optional array of extension paths
+
+Important: `/instances/launch` does not read a `headless` field. Use `mode:"headed"` when you want a headed browser.
## Get One Instance
```bash
curl http://localhost:9867/instances/inst_ea2e747f
-# Response
-{
- "id": "inst_ea2e747f",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9999",
- "headless": false,
- "status": "running",
- "startTime": "2026-03-01T05:21:38.27432Z"
-}
```
Common status values:
@@ -117,7 +89,7 @@ curl http://localhost:9867/instances/inst_ea2e747f/logs
pinchtab instance logs inst_ea2e747f
```
-Response is plain text.
+Response is plain text. There is also an SSE stream at `GET /instances/{id}/logs/stream`.
## Stop An Instance
@@ -125,11 +97,6 @@ Response is plain text.
curl -X POST http://localhost:9867/instances/inst_ea2e747f/stop
# CLI Alternative
pinchtab instance stop inst_ea2e747f
-# Response
-{
- "id": "inst_ea2e747f",
- "status": "stopped"
-}
```
Stopping an instance preserves the profile unless it was a temporary auto-generated profile.
@@ -142,18 +109,9 @@ You can also start an instance from a profile-oriented route:
curl -X POST http://localhost:9867/profiles/prof_278be873/start \
-H "Content-Type: application/json" \
-d '{"headless":false,"port":"9999"}'
-# Response
-{
- "id": "inst_ea2e747f",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9999",
- "headless": false,
- "status": "starting"
-}
```
-This route accepts a profile ID or profile name in the path. Its request body uses `headless` rather than `mode`.
+This route accepts a profile ID or profile name in the path. Unlike `/instances/start` and `/instances/launch`, its request body uses `headless` instead of `mode`.
## Open A Tab In An Instance
@@ -161,35 +119,20 @@ This route accepts a profile ID or profile name in the path. Its request body us
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \
-H "Content-Type: application/json" \
-d '{"url":"https://pinchtab.com"}'
-# Response
-{
- "tabId": "8f9c7d4e1234567890abcdef12345678",
- "url": "https://pinchtab.com",
- "title": "PinchTab"
-}
```
-There is no dedicated instance-scoped `tab open` CLI command today. The CLI shortcut is:
+There is no dedicated instance-scoped `tab open` CLI command. The CLI shortcut is:
```bash
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
```
-That command opens a tab for the instance and then navigates it.
+That command opens a blank tab for the instance and then navigates it.
## List Tabs For One Instance
```bash
curl http://localhost:9867/instances/inst_ea2e747f/tabs
-# Response
-[
- {
- "id": "8f9c7d4e1234567890abcdef12345678",
- "instanceId": "inst_ea2e747f",
- "url": "https://pinchtab.com",
- "title": "PinchTab"
- }
-]
```
## List All Tabs Across Running Instances
@@ -198,7 +141,7 @@ curl http://localhost:9867/instances/inst_ea2e747f/tabs
curl http://localhost:9867/instances/tabs
```
-This is the fleet-wide tab listing endpoint. It is different from `GET /tabs`, which is shorthand/bridge-style and not a fleet-wide inventory.
+This is the fleet-wide tab listing endpoint. It is different from `GET /tabs`, which is shorthand or bridge scoped.
## List Metrics Across Instances
@@ -206,23 +149,12 @@ This is the fleet-wide tab listing endpoint. It is different from `GET /tabs`, w
curl http://localhost:9867/instances/metrics
```
-Use this when you want per-instance memory metrics across all running instances.
-
## Attach An Existing Chrome
```bash
curl -X POST http://localhost:9867/instances/attach \
-H "Content-Type: application/json" \
-d '{"name":"shared-chrome","cdpUrl":"ws://127.0.0.1:9222/devtools/browser/..."}'
-# Response
-{
- "id": "inst_0a89a5bb",
- "profileId": "prof_278be873",
- "profileName": "shared-chrome",
- "status": "running",
- "attached": true,
- "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/..."
-}
```
Notes:
@@ -240,22 +172,10 @@ curl -X POST http://localhost:9867/instances/attach-bridge \
"baseUrl":"http://10.0.12.24:9868",
"token":"bridge-secret-token"
}'
-# Response
-{
- "id": "inst_0a89a5bb",
- "profileId": "prof_278be873",
- "profileName": "shared-bridge",
- "port": "",
- "url": "http://10.0.12.24:9868",
- "status": "running",
- "attached": true,
- "attachType": "bridge"
-}
```
Notes:
-- `baseUrl` must point at a running PinchTab bridge
+- `baseUrl` must point at a running PinchTab bridge and must not include a path
- the orchestrator performs a health check before registering it
- `security.attach.allowHosts` must allow the bridge host
-- `security.attach.allowSchemes` must include `http` or `https` for bridge attachment
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index 47323133..bc4d6ead 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -1,308 +1,100 @@
# MCP Tool Reference
-Complete parameter reference for all 21 tools exposed by the PinchTab MCP server.
+PinchTab currently exposes 34 MCP tools. All tool names are prefixed with `pinchtab_` and are served over stdio JSON-RPC.
-All tool names are prefixed with `pinchtab_`. The server communicates over **stdio JSON-RPC 2.0** (MCP spec 2025-11-25).
+For selector-based interaction tools, prefer `selector`. `ref` is still accepted as a deprecated fallback on the element-action tools.
----
+Selector forms include:
-## Navigation
-
-### pinchtab_navigate
-
-Navigate the browser to a URL.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `url` | string | **Yes** | Full URL including scheme (`http://` or `https://`) |
-| `tabId` | string | No | Target tab. Uses current tab if omitted. |
-
-**Returns:** JSON object with `tabId`, `url`, and `title`.
-
-```json
-{ "tabId": "abc123", "url": "https://example.com", "title": "Example Domain" }
-```
-
----
-
-### pinchtab_snapshot
-
-Get an accessibility tree snapshot of the current page. This is the primary way agents understand page structure and discover interactive element refs.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Target tab |
-| `interactive` | boolean | No | Only return interactive elements (buttons, links, inputs) |
-| `compact` | boolean | No | Compact format — uses fewer tokens |
-| `diff` | boolean | No | Only changes since the last snapshot |
-| `selector` | string | No | CSS selector to scope the snapshot to a subtree |
-
-**Returns:** Accessibility tree as text. Element refs (e.g. `e5`, `e12`) are used in interaction tool calls.
-
----
+- `e5`
+- `#login`
+- `xpath://button`
+- `text:Submit`
+- `find:login button`
-### pinchtab_screenshot
-
-Capture a screenshot of the current page.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Target tab |
-| `quality` | number | No | JPEG quality 0–100 (default PNG) |
-
-**Returns:** Base64-encoded image string.
-
----
-
-### pinchtab_get_text
-
-Extract readable text content from the page, suitable for summarisation and Q&A.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Target tab |
-| `raw` | boolean | No | Return raw text without formatting |
-
-**Returns:** Plain text string.
+## Navigation
----
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_navigate` | `url` required, `tabId` optional | Uses `/navigate`; omitting `tabId` opens a new tab |
+| `pinchtab_snapshot` | `tabId`, `interactive`, `compact`, `diff`, `selector` | `selector` scopes the snapshot |
+| `pinchtab_screenshot` | `tabId`, `format`, `quality` | `format` is `jpeg` or `png` |
+| `pinchtab_get_text` | `tabId`, `raw` | `raw=true` maps to `/text?mode=raw` |
## Interaction
-All interaction tools that target page elements require a `ref` — the element identifier from a `pinchtab_snapshot` response (e.g. `e5`).
-
-### pinchtab_click
-
-Click an element by its accessibility ref.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | Element ref from snapshot (e.g. `e5`) |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_type
-
-Type text into an input element, simulating keystrokes.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | Element ref |
-| `text` | string | **Yes** | Text to type |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_press
-
-Press a named keyboard key.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `key` | string | **Yes** | Key name: `Enter`, `Tab`, `Escape`, `ArrowDown`, `Backspace`, etc. |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_hover
-
-Hover the mouse over an element (triggers `:hover` styles and tooltips).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | Element ref |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_focus
-
-Give keyboard focus to an element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | Element ref |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_select
-
-Select an option from a `<select>` dropdown.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | `<select>` element ref |
-| `value` | string | **Yes** | Option value to select |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_scroll
-
-Scroll the page or a specific element.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | No | Element ref. Omit to scroll the whole page. |
-| `pixels` | number | No | Pixels to scroll. Positive = down/right, negative = up/left. Default 300. |
-| `tabId` | string | No | Target tab |
-
----
-
-### pinchtab_fill
-
-Fill an input field using JavaScript event dispatch. Works with React, Vue, Angular, and other frameworks that intercept native input events.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ref` | string | **Yes** | Element ref or CSS selector |
-| `value` | string | **Yes** | Value to set |
-| `tabId` | string | No | Target tab |
-
-> **Tip:** Use `pinchtab_fill` instead of `pinchtab_type` when the page uses a frontend framework that does not react to raw keystroke simulation.
-
----
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_click` | `selector` required, `tabId`, `ref` | Click element by selector |
+| `pinchtab_type` | `selector` required, `text` required, `tabId`, `ref` | Sends key events |
+| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |
+| `pinchtab_hover` | `selector` required, `tabId`, `ref` | Hover element |
+| `pinchtab_focus` | `selector` required, `tabId`, `ref` | Focus element |
+| `pinchtab_select` | `selector` required, `value` required, `tabId`, `ref` | Select `<option>` by value |
+| `pinchtab_scroll` | `selector`, `pixels`, `tabId`, `ref` | Omit `selector` to scroll the page |
+| `pinchtab_fill` | `selector` required, `value` required, `tabId`, `ref` | Direct fill instead of keystrokes |
+
+## Keyboard
+
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_keyboard_type` | `text` required, `tabId` | Types at the currently focused element |
+| `pinchtab_keyboard_inserttext` | `text` required, `tabId` | Paste-like insert without key events |
+| `pinchtab_keydown` | `key` required, `tabId` | Hold a key down |
+| `pinchtab_keyup` | `key` required, `tabId` | Release a key |
## Content
-### pinchtab_eval
-
-Execute a JavaScript expression in the browser context and return the result.
-
-> **Security note:** Requires `security.allowEvaluate: true` in the PinchTab config. Returns HTTP 403 by default.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `expression` | string | **Yes** | JavaScript expression to evaluate |
-| `tabId` | string | No | Target tab |
-
-**Returns:** JSON-serialised result of the expression.
-
-```javascript
-// Example expressions
-"document.title"
-"document.querySelectorAll('a').length"
-"window.location.href"
-```
-
----
-
-### pinchtab_pdf
-
-Export the current page as a PDF document.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Target tab |
-| `landscape` | boolean | No | Landscape orientation (default portrait) |
-| `scale` | number | No | Print scale 0.1–2.0 (default 1.0) |
-| `pageRanges` | string | No | Pages to include, e.g. `"1-3,5"` |
-
-**Returns:** Base64-encoded PDF bytes.
-
----
-
-### pinchtab_find
-
-Find elements by text content or CSS selector using semantic matching.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | **Yes** | Text content or CSS selector |
-| `tabId` | string | No | Target tab |
-
-**Returns:** List of matching elements with their refs, text, and positions.
-
----
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_eval` | `expression` required, `tabId` | Requires `security.allowEvaluate` |
+| `pinchtab_pdf` | `tabId`, `landscape`, `scale`, `pageRanges` | Returns base64-encoded PDF content |
+| `pinchtab_find` | `query` required, `tabId` | Semantic element search |
## Tab Management
-### pinchtab_list_tabs
-
-List all open browser tabs.
-
-No parameters.
-
-**Returns:** Array of tab objects with `tabId`, `url`, and `title`.
-
----
-
-### pinchtab_close_tab
-
-Close a browser tab.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Tab to close. Closes the current tab if omitted. |
-
----
-
-### pinchtab_health
-
-Check whether the PinchTab server is reachable and healthy.
-
-No parameters.
-
-**Returns:** `{"status":"ok"}` on success.
-
----
-
-### pinchtab_cookies
-
-Get cookies for the current page.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `tabId` | string | No | Target tab |
-
-**Returns:** Array of cookie objects (name, value, domain, path, etc.).
-
----
-
-## Utility
-
-### pinchtab_wait
-
-Wait for a fixed duration. Use sparingly — prefer `pinchtab_wait_for_selector` when possible.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `ms` | number | **Yes** | Milliseconds to wait. Maximum 30000. |
-
----
-
-### pinchtab_wait_for_selector
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_list_tabs` | none | Lists open tabs |
+| `pinchtab_close_tab` | `tabId` | Closes the given tab |
+| `pinchtab_health` | none | Checks server health |
+| `pinchtab_cookies` | `tabId` | Reads cookies for a tab |
+| `pinchtab_connect_profile` | `profile` required | Returns the connect URL and instance status for a profile |
-Wait for a CSS selector to appear on the page. Polls every 250 ms.
+## Wait Utilities
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `selector` | string | **Yes** | CSS selector to wait for |
-| `timeout` | number | No | Timeout in milliseconds. Default 10000, maximum 30000. |
-| `tabId` | string | No | Target tab |
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_wait` | `ms` required | Fixed-duration wait, capped at 30000 ms |
+| `pinchtab_wait_for_selector` | `selector` required, `timeout`, `state`, `tabId` | `state` is `visible` or `hidden` |
+| `pinchtab_wait_for_text` | `text` required, `timeout`, `tabId` | Wait for body text |
+| `pinchtab_wait_for_url` | `url` required, `timeout`, `tabId` | URL glob match |
+| `pinchtab_wait_for_load` | `load` required, `timeout`, `tabId` | Currently supports `networkidle` |
+| `pinchtab_wait_for_function` | `fn` required, `timeout`, `tabId` | JS expression must become truthy |
-**Returns:** `{"present": true}` when the selector is found, `{"present": false}` on timeout.
+## Network
----
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_network` | `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize` | Lists recent network requests |
+| `pinchtab_network_detail` | `requestId` required, `tabId`, `body` | `body=true` includes response body when available |
+| `pinchtab_network_clear` | `tabId` | Clears one tab or all tabs when omitted |
-## Error Responses
+## Dialog
-All tools return errors as MCP tool errors (not Go-level errors). Common error patterns:
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_dialog` | `action` required, `text`, `tabId` | `action` is `accept` or `dismiss` |
-| Situation | Response |
-|-----------|----------|
-| PinchTab not running | Connection refused error |
-| Element ref not found | `HTTP 500: ref not found` |
-| `pinchtab_eval` without security flag | `HTTP 403: evaluate not allowed` |
-| Invalid URL in navigate | `invalid URL: must start with http:// or https://` |
-| Required parameter missing | Parameter validation error from MCP SDK |
+## Return Shapes
----
+Typical results:
-## Related Pages
+- navigation tools return JSON from the matching HTTP endpoint
+- `pinchtab_snapshot` returns snapshot text
+- `pinchtab_get_text` returns page text
+- `pinchtab_screenshot` and `pinchtab_pdf` return JSON containing base64 payloads
+- wait tools return wait status JSON
+- network tools return the same request logs you would see from `/network`
-- [MCP User Guide](../mcp.md)
-- [MCP Architecture](../architecture/mcp.md)
-- [Security Guide](../guides/security.md)
+For setup and client configuration, see [MCP Server](../mcp.md).
diff --git a/docs/reference/scroll.md b/docs/reference/scroll.md
index eba9842c..13f76714 100644
--- a/docs/reference/scroll.md
+++ b/docs/reference/scroll.md
@@ -1,11 +1,11 @@
# Scroll
-Scroll the current tab by direction or pixel amount.
+Scroll the current tab or a specific element.
```bash
curl -X POST http://localhost:9867/action \
-H "Content-Type: application/json" \
- -d '{"kind":"scroll","direction":"down"}'
+ -d '{"kind":"scroll","scrollY":800}'
# CLI Alternative
pinchtab scroll down
# Response
@@ -20,7 +20,8 @@ pinchtab scroll down
Notes:
- the top-level CLI also accepts a pixel value such as `pinchtab scroll 800`
-- the raw API can also use `scrollY`
+- the raw API uses `scrollY` and `scrollX` for page scrolling
+- the raw API can also target an element with `ref` or `selector`
## Related Pages
diff --git a/docs/reference/select.md b/docs/reference/select.md
index 761b64a7..de6b642c 100644
--- a/docs/reference/select.md
+++ b/docs/reference/select.md
@@ -1,6 +1,6 @@
# Select
-Choose a value in a select element by ref.
+Choose a value in a select element by selector or ref.
```bash
curl -X POST http://localhost:9867/action \
@@ -17,7 +17,7 @@ pinchtab select e12 it
}
```
-The `value` should match the option value expected by the page.
+The `value` should match the option value expected by the page. The raw action endpoint accepts `ref` or `selector`, and the CLI accepts the same unified selector forms as the other action commands.
## Related Pages
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index ba2bd469..82366afb 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -1,16 +1,21 @@
# Tabs
-Tabs are the main execution surface for browsing, extracting, and interacting with pages.
+Tabs are the main execution surface for browsing, extraction, interaction, and diagnostics.
-Use tab-scoped routes once you already have a tab ID. Use instance-scoped routes when you need to create a new tab in a specific instance.
+Use tab-scoped HTTP routes once you already have a tab ID. In the CLI, use the normal top-level browser commands with `--tab <id>`.
-Tab IDs should be treated as opaque values returned by the API. Do not construct them yourself or assume one stable format across all routes.
+`pinchtab tab` itself is only for:
-## Shorthand Browser Commands
+- listing tabs
+- focusing a tab
+- opening a new tab
+- closing a tab
-Top-level browser commands such as `nav`, `snap`, `text`, `click`, `type`, `fill`, `pdf`, `ss`, `eval`, and `health` now have their own quick reference pages.
+There are no subcommands such as `pinchtab tab navigate` or `pinchtab tab click`.
-Use those pages when you want the shorthand route plus the matching CLI command:
+## Top-Level Browser Commands
+
+These pages cover the shorthand routes and matching CLI commands:
- [Health](./health.md)
- [Navigate](./navigate.md)
@@ -27,6 +32,7 @@ Use those pages when you want the shorthand route plus the matching CLI command:
- [Scroll](./scroll.md)
- [Select](./select.md)
- [Focus](./focus.md)
+- [Find](./find.md)
## Open A Tab In A Specific Instance
@@ -42,17 +48,17 @@ curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \
}
```
-There is no dedicated instance-scoped `tab open` CLI command today.
-
-If you want a CLI shortcut that opens a tab and navigates it, use:
+There is still no dedicated instance-scoped tab-open CLI command. The CLI shortcut is:
```bash
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
```
+That command opens a tab for the instance and then navigates it.
+
## List Tabs
-### Shorthand Or Bridge List
+### Active Bridge Or Shorthand Context
```bash
curl http://localhost:9867/tabs
@@ -73,184 +79,143 @@ pinchtab tab
Notes:
-- `GET /tabs` is not a fleet-wide orchestrator inventory
+- `GET /tabs` is not a fleet-wide inventory
- in bridge mode or shorthand mode it lists tabs from the active browser context
- `pinchtab tab` follows that shorthand behavior
-### One Instance
+### Tabs For One Instance
```bash
curl http://localhost:9867/instances/inst_ea2e747f/tabs
-# Response
-[
- {
- "id": "8f9c7d4e1234567890abcdef12345678",
- "instanceId": "inst_ea2e747f",
- "url": "https://pinchtab.com",
- "title": "PinchTab"
- }
-]
```
-### All Running Instances
+### Tabs Across All Running Instances
```bash
curl http://localhost:9867/instances/tabs
```
-Use `GET /instances/tabs` when you need the fleet-wide view.
+Use `GET /instances/tabs` when you need the orchestrator-wide view.
-## Navigate An Existing Tab
+## Focus, Create, And Close From The CLI
+
+```bash
+pinchtab tab # list tabs
+pinchtab tab 2 # focus tab by 1-based index
+pinchtab tab 8f9c7d4e1234... # focus tab by tab ID
+pinchtab tab new # open blank tab
+pinchtab tab new https://example.com # open and navigate
+pinchtab tab close 8f9c7d4e1234... # close tab
+```
+
+Numeric arguments are resolved as 1-based indices against `GET /tabs`. Non-numeric arguments are treated as tab IDs.
+
+## Operate On An Existing Tab
+
+Use the tab-scoped HTTP route or the top-level CLI command with `--tab`.
+
+### Navigate
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/navigate \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
# CLI Alternative
-pinchtab tab navigate <tabId> https://example.com
-# Response
-{
- "tabId": "8f9c7d4e1234567890abcdef12345678",
- "url": "https://example.com",
- "title": "Example Domain"
-}
+pinchtab nav https://example.com --tab <tabId>
```
-## Snapshot
+### Snapshot
```bash
curl "http://localhost:9867/tabs/<tabId>/snapshot?interactive=true&compact=true"
# CLI Alternative
-pinchtab tab snapshot <tabId> -i -c
+pinchtab snap --tab <tabId> -i -c
```
-Use this to retrieve the accessibility snapshot and element refs for the page.
-
-## Text
+### Text
```bash
-curl "http://localhost:9867/tabs/<tabId>/text?raw=true"
+curl "http://localhost:9867/tabs/<tabId>/text?mode=raw"
# CLI Alternative
-pinchtab tab text <tabId> --raw
+pinchtab text --tab <tabId> --raw
```
-## Find
+### Find
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/find \
-H "Content-Type: application/json" \
-d '{"query":"login button"}'
-# Response
-{
- "best_ref": "e5",
- "confidence": "high",
- "score": 0.85
-}
+# CLI Alternative
+pinchtab find --tab <tabId> "login button"
```
-There is no dedicated CLI `find` command today.
-
-## Action
+### Actions
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/action \
-H "Content-Type: application/json" \
-d '{"kind":"click","ref":"e5"}'
-# CLI Alternative
-pinchtab tab click <tabId> e5
+# CLI Alternatives
+pinchtab click --tab <tabId> e5
+pinchtab fill --tab <tabId> '#email' '[email protected]'
+pinchtab wait --tab <tabId> 'text:Done'
+pinchtab network --tab <tabId> --limit 20
```
-Other CLI-backed tab operations include:
-
-- `pinchtab tab type <tabId> <ref> <text>`
-- `pinchtab tab fill <tabId> <ref> <text>`
-- `pinchtab tab press <tabId> <key>`
-- `pinchtab tab hover <tabId> <ref>`
-- `pinchtab tab scroll <tabId> <direction|pixels>`
-- `pinchtab tab select <tabId> <ref> <value>`
-- `pinchtab tab focus <tabId> <ref>`
-
-## Screenshot
+### Screenshot
```bash
-curl "http://localhost:9867/tabs/<tabId>/screenshot?raw=true" > out.png
+curl "http://localhost:9867/tabs/<tabId>/screenshot?raw=true" > out.jpg
# CLI Alternative
-pinchtab tab screenshot <tabId> -o out.png
+pinchtab screenshot --tab <tabId> -o out.jpg
```
-## PDF
+### PDF
```bash
curl "http://localhost:9867/tabs/<tabId>/pdf?raw=true" > page.pdf
# CLI Alternative
-pinchtab tab pdf <tabId> -o page.pdf
+pinchtab pdf --tab <tabId> -o page.pdf
```
## Cookies
```bash
curl http://localhost:9867/tabs/<tabId>/cookies
-# CLI Alternative
-pinchtab tab cookies <tabId>
+curl -X POST http://localhost:9867/tabs/<tabId>/cookies \
+ -H "Content-Type: application/json" \
+ -d '{"cookies":[{"name":"session","value":"abc"}]}'
```
+There is no dedicated top-level cookies CLI command today.
+
## Metrics
```bash
curl http://localhost:9867/tabs/<tabId>/metrics
```
-This returns aggregate browser metrics for the tab's owning instance, not isolated per-tab memory.
+This reports memory metrics for the tab through the bridge, not a full per-tab performance profile.
## Lock And Unlock
-Tab lock/unlock is **API-only** — no CLI commands exist yet.
-
-### Lock A Specific Tab
+Tab locking is API-only.
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/lock \
-H "Content-Type: application/json" \
-d '{"owner":"my-agent","ttl":60}'
-```
-### Lock The Active Tab
-
-```bash
-curl -X POST http://localhost:9867/tab/lock \
- -H "Content-Type: application/json" \
- -d '{"owner":"my-agent","ttl":60}'
-```
-
-### Unlock A Specific Tab
-
-```bash
curl -X POST http://localhost:9867/tabs/<tabId>/unlock \
-H "Content-Type: application/json" \
-d '{"owner":"my-agent"}'
```
-### Unlock The Active Tab
-
-```bash
-curl -X POST http://localhost:9867/tab/unlock \
- -H "Content-Type: application/json" \
- -d '{"owner":"my-agent"}'
-```
-
-## Close A Tab
-
-```bash
-curl -X POST http://localhost:9867/tabs/<tabId>/close
-# CLI Alternative
-pinchtab tab close <tabId>
-# Response
-{
- "status": "closed"
-}
-```
+There are also active-tab forms at `POST /tab/lock` and `POST /tab/unlock`.
## Important Limits
-- **There is no `GET /tabs/{id}` endpoint** for fetching single tab info. Use `GET /tabs` to list all tabs or access tab-scoped sub-paths like `/tabs/{id}/snapshot`, `/tabs/{id}/action`, etc.
-- `GET /tabs` and `GET /instances/tabs` serve different purposes and should not be treated as interchangeable
+- There is no `GET /tabs/{id}` endpoint for fetching single-tab metadata.
+- `GET /tabs` and `GET /instances/tabs` serve different purposes and are not interchangeable.
+- In the CLI, tab-scoped work happens through top-level commands with `--tab`, not through `pinchtab tab <subcommand>` variants.
diff --git a/docs/reference/type.md b/docs/reference/type.md
index c4799edd..86c20711 100644
--- a/docs/reference/type.md
+++ b/docs/reference/type.md
@@ -20,7 +20,7 @@ pinchtab type e8 "Ada Lovelace"
Notes:
- use `fill` when you want to set the value more directly
-- top-level `type` expects a ref, not a CSS selector
+- the top-level CLI accepts unified selector forms such as `e8`, `#name`, `xpath://input`, or `text:Name`
## Related Pages