Tab Commands

Manage browser tabs and perform tab-scoped operations

Tab Management

Tabs are individual browser pages within an instance. Each tab has its own navigation history, DOM, and execution context.

List Tabs

pinchtab tabs

Output:

{
  "tabs": [
    {
      "id": "tab_abc123",
      "url": "https://example.com",
      "title": "Example Domain",
      "active": true
    },
    {
      "id": "tab_xyz789",
      "url": "https://github.com",
      "title": "GitHub",
      "active": false
    }
  ]
}

Filter Tabs

# Get all tab IDs
pinchtab tabs | jq -r '.tabs[] | .id'

# Count tabs
pinchtab tabs | jq '.tabs | length'

# Get active tab
pinchtab tabs | jq '.tabs[] | select(.active == true)'

# Find tab by URL
pinchtab tabs | jq '.tabs[] | select(.url | contains("github"))'

Create Tab

pinchtab tab new <url>

Example:

pinchtab tab new https://example.com

Output:

{
  "action": "new",
  "tabId": "tab_abc123",
  "url": "https://example.com"
}

Create without URL (blank tab):

pinchtab tab new

Capture Tab ID

TAB=$(pinchtab tab new https://example.com | jq -r .tabId)
echo "Tab ID: $TAB"

Close Tab

pinchtab tab close <tab-id>

Example:

pinchtab tab close tab_abc123

Output:

{
  "action": "close",
  "tabId": "tab_abc123",
  "status": "closed"
}

Close All Tabs

pinchtab tabs | jq -r '.tabs[] | .id' | xargs -I {} pinchtab tab close {}

Tab Operations

Perform operations on specific tabs using the pinchtab tab <operation> <tabId> pattern.

Navigate Tab

pinchtab tab navigate <tab-id> <url> [flags]

Example:

pinchtab tab navigate tab_abc123 https://github.com

Flags:

--timeout · integer

Navigation timeout in seconds.

pinchtab tab navigate tab_abc123 https://example.com --timeout 30

--block-images · boolean

Block image loading for faster navigation.

pinchtab tab navigate tab_abc123 https://example.com --block-images

--block-ads · boolean

Block known ad domains.

pinchtab tab navigate tab_abc123 https://example.com --block-ads

Snapshot Tab

pinchtab tab snapshot <tab-id> [flags]

Example:

pinchtab tab snapshot tab_abc123 -i -c

Flags:

• -i, --interactive - Interactive elements only
• -c, --compact - Compact format
• -d, --diff - Show only changes

See Snapshot Command for detailed flag documentation.

Screenshot Tab

pinchtab tab screenshot <tab-id> [flags]

Example:

pinchtab tab screenshot tab_abc123 -o screenshot.png

Flags:

-o, --output · string

Output filename.

pinchtab tab screenshot tab_abc123 -o page.png

-q, --quality · integer · default: "80"

JPEG quality (0-100).

pinchtab tab screenshot tab_abc123 -o page.jpg -q 90

Click Element in Tab

pinchtab tab click <tab-id> <ref>

Example:

pinchtab tab click tab_abc123 e5

Type Text in Tab

pinchtab tab type <tab-id> <ref> <text>

Example:

pinchtab tab type tab_abc123 e12 "hello world"

Fill Input in Tab

pinchtab tab fill <tab-id> <ref> <text>

Example:

pinchtab tab fill tab_abc123 e12 "value"

Press Key in Tab

pinchtab tab press <tab-id> <key>

Example:

pinchtab tab press tab_abc123 Enter
pinchtab tab press tab_abc123 Tab
pinchtab tab press tab_abc123 Escape

Scroll Tab

pinchtab tab scroll <tab-id> <direction|pixels>

Examples:

# Scroll by direction
pinchtab tab scroll tab_abc123 down
pinchtab tab scroll tab_abc123 up

# Scroll by pixels
pinchtab tab scroll tab_abc123 500

Select Dropdown in Tab

pinchtab tab select <tab-id> <ref> <value>

Example:

pinchtab tab select tab_abc123 e5 option2

Hover Element in Tab

pinchtab tab hover <tab-id> <ref>

Example:

pinchtab tab hover tab_abc123 e5

Focus Element in Tab

pinchtab tab focus <tab-id> <ref>

Example:

pinchtab tab focus tab_abc123 e12

Extract Text from Tab

pinchtab tab text <tab-id> [--raw]

Example:

# JSON output
pinchtab tab text tab_abc123

# Raw text
pinchtab tab text tab_abc123 --raw

Evaluate JavaScript in Tab

pinchtab tab eval <tab-id> <expression>

Examples:

# Get document title
pinchtab tab eval tab_abc123 "document.title"

# Count links
pinchtab tab eval tab_abc123 "document.querySelectorAll('a').length"

# Complex expression
pinchtab tab eval tab_abc123 'JSON.stringify({title: document.title, url: location.href})'

Export Tab as PDF

pinchtab tab pdf <tab-id> [flags]

Example:

pinchtab tab pdf tab_abc123 -o page.pdf

Flags:

• -o, --output - Output filename
• --landscape - Landscape orientation
• --scale - Print scale (0.1-2.0)

See PDF export documentation for all flags.

Get Tab Cookies

pinchtab tab cookies <tab-id>

Example:

pinchtab tab cookies tab_abc123

Lock Tab

Lock a tab to prevent concurrent access:

pinchtab tab lock <tab-id> [--owner <owner>] [--ttl <seconds>]

Example:

# Lock for 60 seconds
pinchtab tab lock tab_abc123 --owner my-agent --ttl 60

--owner · string

Owner identifier for the lock.

pinchtab tab lock tab_abc123 --owner agent-1

--ttl · integer · default: "60"

Lock time-to-live in seconds.

pinchtab tab lock tab_abc123 --ttl 120

Unlock Tab

pinchtab tab unlock <tab-id> [--owner <owner>]

Example:

pinchtab tab unlock tab_abc123 --owner my-agent

List Tab Locks

pinchtab tab locks <tab-id>

Example:

pinchtab tab locks tab_abc123

Get Tab Info

pinchtab tab info <tab-id>

Example:

pinchtab tab info tab_abc123

Output:

{
  "id": "tab_abc123",
  "url": "https://example.com",
  "title": "Example Domain",
  "active": true,
  "loading": false
}

Common Workflows

Multi-Tab Navigation

# Open multiple tabs
TAB1=$(pinchtab tab new https://github.com | jq -r .tabId)
TAB2=$(pinchtab tab new https://example.com | jq -r .tabId)
TAB3=$(pinchtab tab new https://google.com | jq -r .tabId)

# List all tabs
pinchtab tabs

# Take screenshots of all tabs
pinchtab tab screenshot $TAB1 -o github.png
pinchtab tab screenshot $TAB2 -o example.png
pinchtab tab screenshot $TAB3 -o google.png

# Close all tabs
pinchtab tab close $TAB1
pinchtab tab close $TAB2
pinchtab tab close $TAB3

Tab Isolation

# Each tab has isolated state
TAB=$(pinchtab tab new https://example.com | jq -r .tabId)

# Set cookies in this tab
curl -X POST http://localhost:9867/tabs/$TAB/cookies \
  -d '{"name": "session", "value": "abc123"}'

# Cookies only affect this tab
pinchtab tab cookies $TAB

Parallel Tab Operations

# Get all tab IDs
TABS=$(pinchtab tabs | jq -r '.tabs[] | .id')

# Take screenshots in parallel
for TAB in $TABS; do
  (
    FILE="screenshot-${TAB}.png"
    pinchtab tab screenshot $TAB -o $FILE
    echo "Saved: $FILE"
  ) &
done
wait

echo "All screenshots complete"

Tab Locks for Coordination

# Agent 1: Lock tab
TAB=$(pinchtab tabs | jq -r '.tabs[0].id')
pinchtab tab lock $TAB --owner agent-1 --ttl 120

# Do work on tab
pinchtab tab navigate $TAB https://example.com
pinchtab tab snapshot $TAB -i

# Release lock
pinchtab tab unlock $TAB --owner agent-1

# Agent 2: Can now lock same tab
pinchtab tab lock $TAB --owner agent-2 --ttl 120

Troubleshooting

Tab Not Found

tab not found: tab_abc123

Solution:

# List current tabs
pinchtab tabs

# Verify tab ID
pinchtab tabs | jq -r '.tabs[] | .id'

Too Many Tabs

max tabs limit reached (20)

Solution:

# Close unused tabs
pinchtab tabs | jq -r '.tabs[] | .id' | head -10 | xargs -I {} pinchtab tab close {}

# Or increase limit
export BRIDGE_MAX_TABS=50
pinchtab

Tab Lock Conflict

tab locked by agent-1

Solution:

# Check lock status
pinchtab tab locks tab_abc123

# Wait for lock to expire (TTL)
# Or force unlock (if you own it)
pinchtab tab unlock tab_abc123 --owner agent-1

Tab API Endpoints

Direct HTTP API access:

# List tabs
curl http://localhost:9867/tabs

# Create tab
curl -X POST http://localhost:9867/tab \
  -H "Content-Type: application/json" \
  -d '{"action": "new", "url": "https://example.com"}'

# Close tab
curl -X POST http://localhost:9867/tab \
  -H "Content-Type: application/json" \
  -d '{"action": "close", "tabId": "tab_abc123"}'

# Navigate tab
curl -X POST http://localhost:9867/tabs/tab_abc123/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com"}'

# Snapshot tab
curl "http://localhost:9867/tabs/tab_abc123/snapshot?interactive=true&compact=true"

# Screenshot tab
curl "http://localhost:9867/tabs/tab_abc123/screenshot?raw=true" -o screenshot.png

Next Steps

Navigation

Navigate tabs to URLs

Snapshot

Capture tab structure

Actions

Interact with tab elements

Instance Management

Manage browser instances