Getting Started

Get PinchTab running in a few minutes, from zero to browser automation.

Installation

Option 1: one-liner

macOS / Linux

terminal 
curl -fsSL https://pinchtab.com/install.sh | bash
curl -fsSL https://pinchtab.com/install.sh | bash

Then verify:

terminal 
pinchtab --version
pinchtab --version

Option 2: npm

Requires: Node.js 18+

terminal 
npm install -g pinchtabpinchtab --version
npm install -g pinchtabpinchtab --version

Option 3: Docker

Requires: Docker

terminal 
docker run -d -p 9867:9867 pinchtab/pinchtabcurl http://localhost:9867/health
docker run -d -p 9867:9867 pinchtab/pinchtabcurl http://localhost:9867/health

Option 4: build from source

Requires: Go 1.25+, Git, Chrome/Chromium

terminal 
git clone https://github.com/pinchtab/pinchtab.gitcd pinchtab./pdev doctorgo build -o pinchtab ./cmd/pinchtab./pinchtab --version
git clone https://github.com/pinchtab/pinchtab.gitcd pinchtab./pdev doctorgo build -o pinchtab ./cmd/pinchtab./pinchtab --version

Full build guide ->

Quick start

The normal flow is:

  1. start the server
  2. start an instance
  3. navigate
  4. inspect or act

Step 1: start the server

terminal 
pinchtab
pinchtab
Response 
🦀 PinchTab port=9867
dashboard ready url=http://localhost:9867

The server runs on http://127.0.0.1:9867. You can open the dashboard at http://127.0.0.1:9867 or http://127.0.0.1:9867/dashboard.

Step 2: start your first instance

terminal 
pinchtab instance start
curl -s -X POST http://127.0.0.1:9867/instances/start \  -H "Content-Type: application/json" \  -d '{"mode":"headless"}' | jq .
Response 
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "instance-1741400000000000000",
  "port": "9868",
  "headless": true,
  "status": "starting"
}

Step 3: navigate

terminal 
pinchtab nav https://github.com/pinchtab/pinchtab
curl -s -X POST http://127.0.0.1:9867/navigate \  -H "Content-Type: application/json" \  -d '{"url":"https://github.com/pinchtab/pinchtab"}' | jq .
Response 
{
  "tabId": "CDP_TARGET_ID",
  "title": "GitHub - pinchtab/pinchtab",
  "url": "https://github.com/pinchtab/pinchtab"
}

Step 4: inspect the page

terminal 
pinchtab snap -i -c
curl -s "http://127.0.0.1:9867/snapshot?filter=interactive" | jq .
Response 
{
  "nodes": [
    {
      "ref": "e0",
      "role": "link",
      "name": "Skip to content"
    },
    {
      "ref": "e14",
      "role": "button",
      "name": "Search or jump to…"
    }
  ]
}

You now have a working PinchTab server, a running browser instance, and a navigated tab.

Troubleshooting

Connection refused

terminal 
curl http://localhost:9867/health
curl http://localhost:9867/health

If that fails, start the server:

terminal 
pinchtab
pinchtab

Port already in use

terminal 
PINCHTAB_PORT=9868 pinchtab
PINCHTAB_PORT=9868 pinchtab

Chrome not found

terminal 
# macOSbrew install chromium# Linux (Ubuntu/Debian)sudo apt install chromium-browser# Custom Chrome binaryCHROME_BIN=/path/to/chrome pinchtab
# macOSbrew install chromium# Linux (Ubuntu/Debian)sudo apt install chromium-browser# Custom Chrome binaryCHROME_BIN=/path/to/chrome pinchtab

Getting help