Navigate

Navigate the current tracked tab to a URL, or create a tab when no current tab is available.

terminal 
pinchtab nav https://pinchtab.com
curl -X POST http://localhost:9867/navigate \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'
Response 
8f9c7d4e1234567890abcdef12345678

CLI Flags

pinchtab nav <url> auto-starts the default local server when it is not already running. When --server or PINCHTAB_SERVER targets another server, PinchTab connects to that server without auto-starting a new process. Hidden aliases: goto, navigate, open.

FlagDescription
--tabReuse existing tab
--new-tabForce new tab
--block-imagesBlock image loading
--block-adsBlock ads
--snapOutput snapshot after navigation
--snap-diffOutput snapshot diff after navigation
--print-tab-idPrint only tab ID (auto when piped)
--jsonFull JSON response

Examples

terminal 
pinchtab nav https://example.com              # Navigate current tab, or create onepinchtab nav https://example.com --snap       # Navigate and snapshotTAB=$(pinchtab nav https://example.com)       # Capture tab ID for reusepinchtab nav https://other.com --tab "$TAB"   # Reuse tabpinchtab nav https://example.com --new-tab    # Force another tabpinchtab nav https://example.com --block-images  # Skip images
pinchtab nav https://example.com              # Navigate current tab, or create onepinchtab nav https://example.com --snap       # Navigate and snapshotTAB=$(pinchtab nav https://example.com)       # Capture tab ID for reusepinchtab nav https://other.com --tab "$TAB"   # Reuse tabpinchtab nav https://example.com --new-tab    # Force another tabpinchtab nav https://example.com --block-images  # Skip images

API Body Fields

FieldDescription
urlTarget URL (required)
tabIdReuse existing tab
newTabForce new tab
blockImagesBlock image loading
blockAdsBlock ads
timeoutNavigation timeout
waitForWait condition
waitSelectorWait for selector

Behavior

  • Top-level POST /navigate opens a new tab when no tabId is provided.
  • pinchtab nav <url> uses the current tracked tab when one is available; otherwise it opens a new tab.
  • POST /tabs/{id}/navigate, POST /navigate with tabId, and pinchtab nav <url> --tab <id> reuse the specified tab and make it the current tab for later unscoped operations.
  • --new-tab and newTab:true force a new tab even if another tab is current.
  • Commands that operate without --tab use the current tracked tab. Focusing or using a tab updates that current-tab pointer; if the pointer is stale, PinchTab falls back to the most recently used tracked tab.

Rationale: the CLI keeps one obvious work surface by default. Use --new-tab when you intentionally want another tab, or --tab/tabId when you need a specific tab.