Tabs

Tabs are the main execution surface for browsing, extraction, interaction, and diagnostics.

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>.

pinchtab tab itself is only for:

  • listing tabs
  • focusing a tab
  • opening a new tab
  • closing a tab

There are no subcommands such as pinchtab tab navigate or pinchtab tab click.

Top-Level Browser Commands

These pages cover the shorthand routes and matching CLI commands:

Open A Tab In A Specific Instance

terminal 
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'
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 still no dedicated instance-scoped tab-open CLI command. The CLI shortcut is:

terminal 
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
pinchtab instance navigate inst_ea2e747f https://pinchtab.com

That command opens a tab for the instance and then navigates it.

List Tabs

Active Bridge Or Shorthand Context

terminal 
curl http://localhost:9867/tabs# Response (API always returns JSON){  "tabs": [    {      "id": "8f9c7d4e1234567890abcdef12345678",      "url": "https://pinchtab.com",      "title": "PinchTab",      "type": "page"    }  ]}
Response 
{
  "tabs": [
    {
      "id": "8f9c7d4e1234567890abcdef12345678",
      "url": "https://pinchtab.com",
      "title": "PinchTab",
      "type": "page"
    }
  ]
}

# CLI Alternative (human-readable by default)
pinchtab tab
# Output: *8f9c7d4e...  https://pinchtab.com  PinchTab

pinchtab tab --json                    # Full JSON response

Notes:

  • 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

Tabs For One Instance

terminal 
curl http://localhost:9867/instances/inst_ea2e747f/tabs
curl http://localhost:9867/instances/inst_ea2e747f/tabs

Tabs Across All Running Instances

terminal 
curl http://localhost:9867/instances/tabs
curl http://localhost:9867/instances/tabs

Use GET /instances/tabs when you need the orchestrator-wide view.

Focus And Close From The CLI

terminal 
pinchtab tab                           # list tabspinchtab tab 2                         # focus tab by 1-based indexpinchtab tab 8f9c7d4e1234...           # focus tab by tab IDpinchtab nav https://pinchtab.com --new-tab  # open a new tab and navigate itpinchtab tab close 8f9c7d4e1234...     # close tab
pinchtab tab                           # list tabspinchtab tab 2                         # focus tab by 1-based indexpinchtab tab 8f9c7d4e1234...           # focus tab by tab IDpinchtab nav https://pinchtab.com --new-tab  # open a new tab and navigate itpinchtab tab close 8f9c7d4e1234...     # close tab

Numeric arguments are resolved as 1-based indices against GET /tabs. Non-numeric arguments are treated as tab IDs.

Focusing, navigating, or otherwise accessing a tracked tab marks it as the current tab. Unscoped commands use that current tab; if the recorded current tab has gone stale, PinchTab falls back to the most recently used tracked tab.

Top-level navigation uses the current tab when one is available. Use pinchtab nav <url> --new-tab when you explicitly want another tab.

Operate On An Existing Tab

Use the tab-scoped HTTP route or the top-level CLI command with --tab.

terminal 
pinchtab nav https://pinchtab.com --tab <tabId>
curl -X POST http://localhost:9867/tabs/<tabId>/navigate \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'

Snapshot

terminal 
pinchtab snap --tab <tabId> -i -c
curl "http://localhost:9867/tabs/<tabId>/snapshot?interactive=true&compact=true"

Text

terminal 
pinchtab text --tab <tabId> --raw
curl "http://localhost:9867/tabs/<tabId>/text?mode=raw"

Find

terminal 
pinchtab find --tab <tabId> "login button"
curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"login button"}'

Actions

terminal 
pinchtab click --tab <tabId> e5pinchtab fill --tab <tabId> '#email' 'ada@example.com'pinchtab wait --tab <tabId> 'text:Done'pinchtab network --tab <tabId> --limit 20
curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"click","ref":"e5"}'

Low-level pointer control uses the same action surface:

terminal 
pinchtab mouse move --tab <tabId> e5pinchtab mouse down --tab <tabId> --button leftpinchtab mouse wheel --tab <tabId> 240 --dx 40
curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","ref":"e5"}'curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-down","button":"left"}'curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-wheel","x":400,"y":320,"deltaY":240}'

Handoff State

Human handoff is tab-scoped and available through CLI or API.

terminal 
pinchtab tab handoff <tabId> --reason captcha --timeout-ms 120000pinchtab tab handoff-status <tabId>pinchtab tab resume <tabId> --status completed
pinchtab tab handoff <tabId> --reason captcha --timeout-ms 120000pinchtab tab handoff-status <tabId>pinchtab tab resume <tabId> --status completed

API equivalents:

When a tab is marked paused_handoff, action execution routes reject with 409 tab_paused_handoff until the tab is resumed or the optional timeout expires.

terminal 
curl -X POST http://localhost:9867/tabs/<tabId>/handoff \  -H "Content-Type: application/json" \  -d '{"reason":"captcha","timeoutMs":120000}'curl http://localhost:9867/tabs/<tabId>/handoffcurl -X POST http://localhost:9867/tabs/<tabId>/resume \  -H "Content-Type: application/json" \  -d '{"status":"completed","resolvedData":{"operator":"human"}}'
curl -X POST http://localhost:9867/tabs/<tabId>/handoff \  -H "Content-Type: application/json" \  -d '{"reason":"captcha","timeoutMs":120000}'curl http://localhost:9867/tabs/<tabId>/handoffcurl -X POST http://localhost:9867/tabs/<tabId>/resume \  -H "Content-Type: application/json" \  -d '{"status":"completed","resolvedData":{"operator":"human"}}'

Use this when automation must pause for a CAPTCHA, 2FA prompt, login approval, or another human-only step. When a timeout is provided, handoff status includes expiresAt and timeoutMs.

Screenshot

terminal 
pinchtab screenshot --tab <tabId> -o out.jpg
curl "http://localhost:9867/tabs/<tabId>/screenshot?raw=true" > out.jpg

PDF

terminal 
pinchtab pdf --tab <tabId> -o page.pdf
curl "http://localhost:9867/tabs/<tabId>/pdf?raw=true" > page.pdf

Cookies

terminal 
curl http://localhost:9867/tabs/<tabId>/cookiescurl -X POST http://localhost:9867/tabs/<tabId>/cookies \  -H "Content-Type: application/json" \  -d '{"cookies":[{"name":"session","value":"abc"}]}'
curl http://localhost:9867/tabs/<tabId>/cookiescurl -X POST http://localhost:9867/tabs/<tabId>/cookies \  -H "Content-Type: application/json" \  -d '{"cookies":[{"name":"session","value":"abc"}]}'

A pinchtab cookies CLI command is available; today it exposes a single subcommand:

terminal 
pinchtab cookies clear     # clear all cookies via CDP (affects all origins)
pinchtab cookies clear     # clear all cookies via CDP (affects all origins)

Reading, writing, and clearing cookies requires security.allowCookies=true.

Metrics

terminal 
curl http://localhost:9867/tabs/<tabId>/metrics
curl http://localhost:9867/tabs/<tabId>/metrics

This reports memory metrics for the tab through the bridge, not a full per-tab performance profile.

Lock And Unlock

Tab locking is API-only.

terminal 
curl -X POST http://localhost:9867/tabs/<tabId>/lock \  -H "Content-Type: application/json" \  -d '{"owner":"my-agent","ttl":60}'curl -X POST http://localhost:9867/tabs/<tabId>/unlock \  -H "Content-Type: application/json" \  -d '{"owner":"my-agent"}'
curl -X POST http://localhost:9867/tabs/<tabId>/lock \  -H "Content-Type: application/json" \  -d '{"owner":"my-agent","ttl":60}'curl -X POST http://localhost:9867/tabs/<tabId>/unlock \  -H "Content-Type: application/json" \  -d '{"owner":"my-agent"}'

There are also active-tab forms at POST /lock and POST /unlock.

Important Limits

  • 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 — except for handoff, resume, and handoff-status, which are exposed both as top-level commands and as pinchtab tab handoff|resume|handoff-status subcommands.