docs/get-started.md

Getting Started

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

---

Installation

Option 1: one-liner

macOS / Linux

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

Then verify:

pinchtab --version

Option 2: npm

Requires: Node.js 18+

npm install -g pinchtab
pinchtab --version

Option 3: Docker

Requires: Docker

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

Option 4: build from source

Requires: Go 1.25+, Git, Chrome/Chromium

git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./dev doctor
go build -o pinchtab ./cmd/pinchtab
./pinchtab --version

Full build guide ->

Shell Completion

After installation, you can generate shell completions from the CLI:

# Generate and install zsh completions
pinchtab completion zsh > "${fpath[1]}/_pinchtab"

# Generate bash completions
pinchtab completion bash > /etc/bash_completion.d/pinchtab

# Generate fish completions
pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish

---

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

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

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

Step 3: navigate

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

Step 4: inspect the page

curl -s "http://127.0.0.1:9867/snapshot?filter=interactive" | jq .
# CLI Alternative
pinchtab snap -i -c
# 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

curl http://localhost:9867/health

If that fails, start the server:

pinchtab

Port already in use

pinchtab config set server.port 9868
pinchtab

Chrome not found

# macOS
brew install chromium

# Linux (Ubuntu/Debian)
sudo apt install chromium-browser

# Custom Chrome binary (set in config)
pinchtab config set browser.chromeBinary /path/to/chrome

---

Getting help

• GitHub Issues
• GitHub Discussions