CLI Quick Reference

# Headless (default)pinchtab instance launch# Headed (with window)pinchtab instance launch --mode headed# On specific portpinchtab instance launch --port 9868# Get instance IDINST=$(pinchtab instance launch --mode headed | jq -r .id)echo $INST  # inst_abc123

pinchtab instances# Get just IDspinchtab instances | jq -r '.[] | .id'# Get specific instancepinchtab instances | jq '.[] | select(.id == "inst_abc123")'

pinchtab instance inst_abc123 logs# Follow logs (continuous)pinchtab instance inst_abc123 logs | tail -f# Last 100 linespinchtab instance inst_abc123 logs | tail -100

pinchtab instance inst_abc123 stop

# Default instancepinchtab nav https://example.com# Specific instancepinchtab --instance inst_abc123 nav https://example.com# Open in new tabpinchtab --instance inst_abc123 nav https://example.com --new-tab# Without images (faster)pinchtab --instance inst_abc123 nav https://example.com --block-images

# Full pagepinchtab --instance inst_abc123 snap# Interactive elements onlypinchtab --instance inst_abc123 snap -i# Compact (token-efficient)pinchtab --instance inst_abc123 snap -c# Interactive + compact (best for AI)pinchtab --instance inst_abc123 snap -i -c# Only changes since last snapshotpinchtab --instance inst_abc123 snap -d# Save to filepinchtab --instance inst_abc123 snap > page.json# Parse in scriptpinchtab --instance inst_abc123 snap -c | jq '.elements[] | .ref' | head -5

pinchtab --instance inst_abc123 click e5

pinchtab --instance inst_abc123 type e12 "hello world"

pinchtab --instance inst_abc123 fill e12 "value"

pinchtab --instance inst_abc123 press Enterpinchtab --instance inst_abc123 press Tabpinchtab --instance inst_abc123 press Escape

pinchtab --instance inst_abc123 scroll downpinchtab --instance inst_abc123 scroll uppinchtab --instance inst_abc123 scroll 500  # pixels

pinchtab --instance inst_abc123 text# Raw text (no JSON wrapper)pinchtab --instance inst_abc123 text --raw

# To stdout (PNG)pinchtab --instance inst_abc123 ss > screenshot.png# To filepinchtab --instance inst_abc123 ss -o out.png# JPEG with qualitypinchtab --instance inst_abc123 ss -o out.jpg -q 85

# Default (A4 portrait)pinchtab --instance inst_abc123 pdf -o out.pdf# Landscapepinchtab --instance inst_abc123 pdf -o out.pdf --landscape# Letter sizepinchtab --instance inst_abc123 pdf -o out.pdf --paper-width 8.5 --paper-height 11# Specific pagespinchtab --instance inst_abc123 pdf -o out.pdf --page-ranges "1-3,5"

pinchtab --instance inst_abc123 eval "document.title"# JSON resultpinchtab --instance inst_abc123 eval "document.querySelectorAll('a').length"# Complex scriptpinchtab --instance inst_abc123 eval '  JSON.stringify({    title: document.title,    url: location.href,    links: document.querySelectorAll("a").length  })'

pinchtab --instance inst_abc123 tabs# Get tab IDspinchtab --instance inst_abc123 tabs | jq -r '.tabs[] | .id'# Count tabspinchtab --instance inst_abc123 tabs | jq '.tabs | length'

# Create and get IDTAB=$(pinchtab --instance inst_abc123 tab create https://example.com | jq -r .id)echo $TAB  # tab_xyz789

pinchtab --instance inst_abc123 tab tab_xyz789 navigate https://google.com

pinchtab --instance inst_abc123 tab tab_xyz789 close

# Lock for 60 secondspinchtab --instance inst_abc123 tab tab_xyz789 lock --owner my-agent --ttl 60# After work, unlockpinchtab --instance inst_abc123 tab tab_xyz789 unlock --owner my-agent

cat << 'EOF' | pinchtab --instance inst_abc123 action{  "kind": "actions",  "actions": [    {"kind": "click", "ref": "e1"},    {"kind": "type", "ref": "e2", "text": "search query"},    {"kind": "press", "key": "Enter"},    {"kind": "wait", "time": 2000},    {"kind": "click", "ref": "e5"}  ]}EOF

# Create actions filecat > actions.json << 'EOF'{  "kind": "actions",  "actions": [    {"kind": "click", "ref": "e1"},    {"kind": "type", "ref": "e2", "text": "hello"},    {"kind": "press", "key": "Enter"}  ]}EOF# Run itpinchtab --instance inst_abc123 action -f actions.json

pinchtab --instance inst_abc123 action --json '{"kind":"click","ref":"e5"}'

# Terminal 1: Start the dashboard/orchestratorpinchtab# Now listening on http://localhost:9867

# Terminal 2: Launch a headed instanceINST=$(pinchtab instance launch --mode headed | jq -r .id)echo "Instance: $INST"

# Navigate to websitepinchtab --instance $INST nav https://github.com/pinchtab/pinchtab# See page structurepinchtab --instance $INST snap -i -c | jq .# Click button (find e5 from snapshot)pinchtab --instance $INST click e5# See resultpinchtab --instance $INST snap -i -c | jq '.elements[] | select(.ref == "e5")'

# Get all visible textpinchtab --instance $INST text --raw# Count linkspinchtab --instance $INST eval 'document.querySelectorAll("a").length'# Export pagepinchtab --instance $INST pdf -o page.pdf

# Stop instancepinchtab instance $INST stop# Verify stoppedpinchtab instances

# Launch 3 instancesfor i in {1..3}; do  PORT=$((9868 + i))  INST=$(pinchtab instance launch --mode headed --port $PORT | jq -r .id)  echo "Instance $i: $INST"done

# Navigate multiple instances concurrentlyfor inst in $(pinchtab instances | jq -r '.[] | .id'); do  (pinchtab --instance $inst nav https://example.com) &donewaitecho "All instances navigated"

# Watch instance statuswhile true; do  clear  pinchtab instances | jq -r '.[] | "\(.id) (\(.mode)): \(.status)"'  sleep 2done

# Stop all instancespinchtab instances | jq -r '.[] | .id' | xargs -I {} pinchtab instance {} stop

pinchtab health# Should print: {"status": "ok"}

# If running in foreground, Ctrl+C to see logs# If running in background:jobsfg  # bring to foreground

# Check logspinchtab instance inst_abc123 logs | tail -50# Check port availabilitylsof -i :9868

# Verify instance is runningpinchtab instances | jq '.[] | select(.id == "inst_abc123")'# Check statuspinchtab instances | jq '.[] | select(.id == "inst_abc123") | .status'# Should be "running"

# For remote serverexport PINCHTAB_URL=http://192.168.1.100:9867# Or per-command (coming soon)pinchtab --server http://192.168.1.100:9867 instances

# Server address (if not on localhost:9867)export PINCHTAB_URL=http://localhost:9867# Server port (alternative to PINCHTAB_URL)export BRIDGE_PORT=9868# Default instance (skip --instance flag)export PINCHTAB_INSTANCE=inst_abc123# Auth tokenexport PINCHTAB_TOKEN=sk_xxx# Request timeoutexport PINCHTAB_TIMEOUT=30# Output formatexport PINCHTAB_FORMAT=json  # json, text (coming soon)# Disable colorsexport PINCHTAB_NO_COLOR=1

pinchtab --instance inst_abc123 nav https://example.comsleep 2  # Wait for pagepinchtab --instance inst_abc123 snap -i

pinchtab --instance inst_abc123 click e5sleep 1pinchtab --instance inst_abc123 ss -o result.png

pinchtab --instance inst_abc123 fill e1 "John Doe"pinchtab --instance inst_abc123 fill e2 "john@example.com"pinchtab --instance inst_abc123 click e3  # Submit buttonsleep 2pinchtab --instance inst_abc123 snap

pinchtab --instance inst_abc123 nav https://google.compinchtab --instance inst_abc123 fill e1 "golang"pinchtab --instance inst_abc123 press Entersleep 2pinchtab --instance inst_abc123 text | grep -q "golang"echo "Search results found"

pinchtab instance inst_abc123 logsecho $?  # 0 = successpinchtab --instance nonexistent snapecho $?  # 4 = not foundpinchtab instance launch --invalid-flagecho $?  # 1 = user errorcurl http://localhost:9867/health > /dev/null || {  echo "Server down"  # 2 = server error}