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

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

Then verify:

```bash
pinchtab --version
```

### Option 2: npm

**Requires:** Node.js 18+

```bash
npm install -g pinchtab
pinchtab --version
```

### Option 3: Docker

**Requires:** Docker

```bash
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

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

**[Full build guide ->](architecture/building.md)**

## Shell Completion

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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
curl http://localhost:9867/health
```

If that fails, start the server:

```bash
pinchtab
```

### Port already in use

```bash
pinchtab config set server.port 9868
pinchtab
```

### Chrome not found

```bash
# 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](https://github.com/pinchtab/pinchtab/issues)
- [GitHub Discussions](https://github.com/pinchtab/pinchtab/discussions)