File size: 4,245 Bytes
6a7089a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | # Pinchtab npm
Browser control API for AI agents — Node.js SDK + CLI wrapper.
## Installation
```bash
npm install pinchtab
```
or globally:
```bash
npm install -g pinchtab
```
On install, the postinstall script automatically:
1. Detects your OS and CPU architecture (darwin/linux/windows, amd64/arm64)
2. Downloads the precompiled Pinchtab binary from GitHub Releases
- Example: `pinchtab-darwin-amd64`, `pinchtab-linux-arm64.exe` (Windows)
3. Verifies integrity (SHA256 checksum from `checksums.txt`)
4. Stores in `~/.pinchtab/bin/0.7.1/` (version-specific to avoid conflicts)
5. Makes it executable
**Requirements:**
- Internet connection on first install (to download binary from GitHub Releases)
- Node.js 16+
- macOS, Linux, or Windows
### Proxy Support
Works with corporate proxies. Set standard environment variables:
```bash
npm install --https-proxy https://proxy.company.com:8080 pinchtab
# or
export HTTPS_PROXY=https://user:pass@proxy.company.com:8080
npm install pinchtab
```
## Quick Start
### Start the server
```bash
pinchtab serve --port 9867
```
### Use the SDK
```typescript
import Pinchtab from 'pinchtab';
const pinch = new Pinchtab({ port: 9867 });
// Start the server
await pinch.start();
// Take a snapshot
const snapshot = await pinch.snapshot({ refs: 'role' });
console.log(snapshot.html);
// Click on an element
await pinch.click({ ref: 'e42' });
// Lock a tab
await pinch.lock({ tabId: 'tab1', timeoutMs: 5000 });
// Stop the server
await pinch.stop();
```
## API
### `new Pinchtab(options)`
Create a Pinchtab client.
**Options:**
- `baseUrl` (string): API base URL. Default: `http://localhost:9867`
- `timeout` (number): Request timeout in ms. Default: `30000`
- `port` (number): Port to run on. Default: `9867`
### `start(binaryPath?)`
Start the Pinchtab server process.
### `stop()`
Stop the Pinchtab server process.
### `snapshot(params?)`
Take a snapshot of the current tab.
**Params:**
- `refs` ('role' | 'aria'): Reference system
- `selector` (string): CSS selector filter
- `maxTokens` (number): Token limit
- `format` ('full' | 'compact'): Response format
### `click(params)`
Click on an element.
**Params:**
- `ref` (string): Element reference
- `targetId` (string): Optional target tab ID
### `lock(params)` / `unlock(params)`
Lock/unlock a tab.
### `createTab(params)`
Create a new tab.
**Params:**
- `url` (string): Tab URL
- `stealth` ('light' | 'full'): Stealth level
## CLI
```bash
pinchtab serve [--port PORT]
pinchtab --version
pinchtab --help
```
### Shell Completion
After installing the CLI globally, you can generate shell completions:
```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
```
### Using a Custom Binary
For Docker, development, or other custom setups:
```bash
PINCHTAB_BINARY_PATH=/path/to/pinchtab npx pinchtab serve
```
Or in code:
```typescript
const pinch = new Pinchtab();
const binaryPath = '/custom/path/to/pinchtab';
await pinch.start(binaryPath);
```
## Troubleshooting
**Binary not found or "file not found" error:**
Check if the release has binaries:
```bash
# Should show pinchtab-darwin-arm64, pinchtab-linux-x64, etc.
curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/latest | jq '.assets[].name'
```
If no binaries (only Docker images), rebuild with a newer release:
```bash
npm rebuild pinchtab
```
Or use a custom binary:
```bash
export PINCHTAB_BINARY_PATH=/path/to/pinchtab
npm rebuild pinchtab
```
**Behind a proxy:**
```bash
export HTTPS_PROXY=https://proxy:port
npm rebuild pinchtab
```
**Using a pre-built binary:**
```bash
PINCHTAB_BINARY_PATH=/path/to/binary npm rebuild pinchtab
```
## Future: OptionalDependencies Pattern (v1.0)
In a future major version, we plan to migrate to the modern `optionalDependencies` pattern used by esbuild, Biome, Turbo, etc. This will split platform-specific binaries into separate npm packages (@pinchtab/cli-darwin-arm64, etc.) for zero postinstall network overhead and perfect offline support.
## License
MIT
|