High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: comprehensive cli commands reference
Mariobd4f113d113c
diff --git a/docs/cli-commands.md b/docs/cli-commands.mdnew file mode 100644index 00000000..886c737e--- /dev/null+++ b/docs/cli-commands.md@@ -0,0 +1,628 @@+# Pinchtab CLI Commands++Complete reference for all `pinchtab` CLI commands. Requires a running Pinchtab server (except for `help`).++## Quick Start++**Terminal 1: Start the server**+```bash+pinchtab+```++**Terminal 2: Use CLI commands**+```bash+pinchtab quick https://example.com # Navigate + analyze page+```++## Server Control++Start Pinchtab in different modes.++### Start Server+```bash+pinchtab+```+Launches Pinchtab server on `http://127.0.0.1:9867` (default).++**Options:**+```bash+BRIDGE_PORT=9868 pinchtab # Custom port+BRIDGE_HEADLESS=false pinchtab # Visible window+BRIDGE_PROFILE=/path/to/profile pinchtab # Custom profile+BRIDGE_TOKEN=secret pinchtab # Enable auth+```++### Dashboard (Profile Manager)+```bash+pinchtab dashboard+```+Run the orchestrator and profile manager (no browser).++### Connect to Running Profile+```bash+pinchtab connect <name>+```+Get the URL for a running Chrome profile.++---++## CLI Commands (Require Running Server)++### Quick Start Command++#### Navigate + Analyze Page+```bash+pinchtab quick <url>+```+**New beginner-friendly command that combines navigation and page analysis in one step.**++- Navigates to the URL+- Waits for page to load+- Shows page structure with clickable elements+- Suggests next actions (click, type, screenshot, PDF)++**Example:**+```bash+$ pinchtab quick https://example.com+π¦ Navigating to https://example.com ...++π Page structure:+[accessible tree output]++π Title: Example Domain+π URL: https://example.com/++π‘ Quick actions:+ pinchtab click <ref> # Click an element (use refs from above)+ pinchtab type <ref> <text> # Type into input field+ pinchtab screenshot # Take a screenshot+ pinchtab pdf -o output.pdf # Save as PDF+```++---++### Navigation++#### Navigate to URL+```bash+pinchtab nav <url>+pinchtab navigate <url> # Alias+```++**Options:**+```bash+pinchtab nav https://example.com --new-tab+pinchtab nav https://example.com --block-images+pinchtab nav https://example.com --block-ads+```++**Flags:**+- `--new-tab` β Open in new tab instead of current+- `--block-images` β Don't load images+- `--block-ads` β Block 100+ tracking/ad domains++**Example:**+```bash+pinchtab nav https://example.com+# Returns: {"title": "Example Domain", "url": "https://example.com"}+```++---++### Snapshots & DOM++#### Get Accessibility Tree+```bash+pinchtab snap+pinchtab snapshot # Alias+```++**Options:**+```bash+pinchtab snap -i # Interactive only (buttons, links, inputs)+pinchtab snap -c # Compact format (most token-efficient)+pinchtab snap -d # Diff only (changes since last snapshot)+pinchtab snap -i -c # Combine flags+pinchtab snap -s "main > form" # CSS selector scope+pinchtab snap --max-tokens 1000 # Truncate to ~1000 tokens+pinchtab snap --depth 3 # Max tree depth+pinchtab snap --tab <tabId> # Target specific tab+```++**Flags:**+- `-i, --interactive` β Only buttons, links, inputs (faster, fewer tokens)+- `-c, --compact` β Compact JSON format (most token-efficient for AI)+- `-d, --diff` β Only elements that changed since last snapshot+- `-s, --selector CSS` β Scope to CSS selector+- `--max-tokens N` β Truncate output to ~N tokens+- `--depth N` β Max tree depth+- `--tab ID` β Target specific tab (default: first tab)++**Output Structure:**+```json+{+ "elements": [+ {+ "ref": "e0",+ "role": "heading",+ "name": "Example Domain",+ "visible": true+ },+ {+ "ref": "e1",+ "role": "link",+ "name": "More information...",+ "visible": true+ }+ ]+}+```++---++### Interaction++#### Click Element+```bash+pinchtab click <ref>+```++**Example:**+```bash+pinchtab click e5 # Click element with ref e5+```++#### Type Text+```bash+pinchtab type <ref> <text>+```++**Example:**+```bash+pinchtab type e12 "hello world"+pinchtab type e3 "[email protected]"+```++#### Fill Input (Direct)+```bash+pinchtab fill <ref|selector> <text>+```+Sets input value directly without triggering key events.++**Example:**+```bash+pinchtab fill e5 "value"+pinchtab fill "input[name='email']" "[email protected]"+```++#### Press Key+```bash+pinchtab press <key>+```++**Keys:** `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, etc.++**Example:**+```bash+pinchtab press Enter+pinchtab press Tab+pinchtab press Escape+```++#### Hover Element+```bash+pinchtab hover <ref>+```++**Example:**+```bash+pinchtab hover e5+```++#### Focus Element+```bash+pinchtab focus <ref>+```++**Example:**+```bash+pinchtab focus e5+```++#### Scroll+```bash+pinchtab scroll <ref|pixels>+```++Scroll to element or by pixel amount.++**Example:**+```bash+pinchtab scroll e5 # Scroll to element+pinchtab scroll 500 # Scroll down 500px+```++#### Select Dropdown+```bash+pinchtab select <ref> <value>+```++**Example:**+```bash+pinchtab select e7 "Option 2"+```++---++### Content Extraction++#### Extract Text+```bash+pinchtab text+pinchtab text --raw # Raw innerText (no readability)+```++**Modes:**+- Default β Readability extraction (strips nav, ads, sidebars)+- `--raw` β Raw `innerText` (full page text)++**Example:**+```bash+pinchtab text # Returns readable article/content+pinchtab text --raw # Returns all text on page+pinchtab text | jq .text # Pipe output to jq+```++#### Evaluate JavaScript+```bash+pinchtab eval <expression>+pinchtab evaluate <expression> # Alias+```++**Escape hatch to run any JavaScript.**++**Example:**+```bash+pinchtab eval "document.title"+pinchtab eval "document.querySelectorAll('a').length"+pinchtab eval "localStorage.getItem('token')"+```++---++### Capture & Export++#### Screenshot+```bash+pinchtab ss+pinchtab screenshot # Alias+```++**Options:**+```bash+pinchtab ss -o screenshot.jpg+pinchtab ss -q 85 # Quality 0-100 (default: 90)+pinchtab ss -o page.jpg -q 80+```++**Flags:**+- `-o, --output FILE` β Save to file (default: stdout)+- `-q, --quality N` β JPEG quality 0-100 (default: 90)++**Example:**+```bash+pinchtab ss -o page.jpg+pinchtab ss -o page.jpg -q 75+```++#### Export PDF+```bash+pinchtab pdf+pinchtab pdf -o output.pdf+```++**Basic Options:**+```bash+pinchtab pdf -o output.pdf+pinchtab pdf -o report.pdf --landscape+pinchtab pdf -o report.pdf --scale 1.5+pinchtab pdf -o report.pdf --page-ranges "1-3,5"+```++**Paper & Margins:**+```bash+pinchtab pdf --paper-width 8.5 --paper-height 11 # US Letter (default)+pinchtab pdf --paper-width 210 --paper-height 297 # A4 (in mm)+pinchtab pdf --margin-top 0.5 --margin-bottom 0.5+pinchtab pdf --margin-left 1.0 --margin-right 1.0+pinchtab pdf --prefer-css-page-size # Honor CSS @page size+```++**Headers & Footers:**+```bash+pinchtab pdf --display-header-footer+pinchtab pdf --header-template "<div>Page <span class='pageNumber'></span></div>"+pinchtab pdf --footer-template "<div>Β© 2024</div>"+```++**Accessibility:**+```bash+pinchtab pdf --generate-tagged-pdf # Create accessible PDF+pinchtab pdf --generate-document-outline # Add document outline/bookmarks+```++**File Output:**+```bash+pinchtab pdf --file-output # Save to server disk+pinchtab pdf --file-output --path /tmp/output.pdf+```++**All Options:**+```bash+pinchtab pdf -o output.pdf \+ --landscape \+ --paper-width 8.5 \+ --paper-height 11 \+ --margin-top 0.5 \+ --margin-bottom 0.5 \+ --margin-left 1.0 \+ --margin-right 1.0 \+ --scale 1.0 \+ --page-ranges "1-5" \+ --prefer-css-page-size \+ --display-header-footer \+ --header-template "<h1>Report</h1>" \+ --footer-template "<p>Page <span class='pageNumber'></span></p>" \+ --generate-tagged-pdf \+ --generate-document-outline \+ --tab tabId123+```++---++### Tab Management++#### List Tabs+```bash+pinchtab tabs+pinchtab tab # Alias+```++**Returns:** JSON array of open tabs with `tabId`, `title`, `url`.++**Example:**+```bash+$ pinchtab tabs+[+ {+ "tabId": "abc123",+ "title": "Example Domain",+ "url": "https://example.com"+ }+]+```++#### Open New Tab+```bash+pinchtab tabs new <url>+pinchtab tab new <url> # Alias+```++**Example:**+```bash+pinchtab tabs new https://google.com+```++#### Close Tab+```bash+pinchtab tabs close <tabId>+pinchtab tab close <tabId> # Alias+```++**Example:**+```bash+pinchtab tabs close abc123+```++---++### Server & Help++#### Health Check+```bash+pinchtab health+```++**Example:**+```bash+$ pinchtab health+{+ "status": "ok",+ "version": "0.7.6",+ "uptime": 3600+}+```++#### Show Help+```bash+pinchtab help+```++Displays all commands and options.++---++## Environment Variables++Configure Pinchtab behavior via environment variables.++### Client Variables+Used by CLI commands:++```bash+PINCHTAB_URL=http://localhost:9867 # Server URL (default: http://127.0.0.1:9867)+PINCHTAB_TOKEN=your-secret-token # Auth token (sent as Bearer)+```++### Server Variables+Used when running `pinchtab` server:++```bash+BRIDGE_PORT=9867 # Server port (default: 9867)+BRIDGE_BIND=0.0.0.0 # Bind address (default: 127.0.0.1)+BRIDGE_HEADLESS=true # Headless mode (default: true)+BRIDGE_PROFILE=/path/to/profile # Chrome profile directory+BRIDGE_TOKEN=your-secret-token # API auth token+BRIDGE_BLOCK_ADS=true # Block 100+ ad domains+BRIDGE_NO_RESTORE=false # Don't restore tabs on startup+CDP_URL=http://localhost:9222 # Connect to external Chrome (instead of launching)+```++---++## Examples++### Basic Workflow+```bash+# Terminal 1: Start server+pinchtab++# Terminal 2: Interact+pinchtab nav https://example.com+pinchtab snap -i -c # See interactive elements+pinchtab click e5 # Click element+pinchtab snap # Verify change+pinchtab screenshot -o result.jpg # Capture result+```++### Form Filling+```bash+pinchtab nav https://example.com/form+pinchtab snap -i -c # Find input refs+pinchtab click e1 # Focus first field+pinchtab type e1 "John Doe" # Type name+pinchtab click e2 # Focus email field+pinchtab type e2 "[email protected]" # Type email+pinchtab click e5 # Click submit+pinchtab snap # Verify submission+```++### Scraping with Text Extraction+```bash+pinchtab nav https://example.com/article+pinchtab text > article.txt # Extract text+pinchtab text | jq .text # Parse JSON+```++### PDF Generation+```bash+pinchtab nav https://example.com/report+pinchtab pdf -o report.pdf \+ --landscape \+ --page-ranges "1-5" \+ --display-header-footer \+ --header-template "<h1>Report</h1>"+```++### Multi-Tab Automation+```bash+pinchtab nav https://google.com+pinchtab tabs new https://github.com+pinchtab tabs # List both tabs+pinchtab snap --tab tab2 # Snapshot second tab+```++### With Authentication+```bash+PINCHTAB_TOKEN=secret-token pinchtab nav https://api.example.com+PINCHTAB_URL=http://192.168.1.100:9867 pinchtab snap+```++### Piping with jq+```bash+# Get all links on page+pinchtab snap -i -c | jq '.elements[] | select(.role=="link") | {ref, name}'++# Extract readable text as JSON+pinchtab text | jq '.text'++# List all tabs+pinchtab tabs | jq '.[] | {tabId, title, url}'+```++---++## Tips++### Token Efficiency+For AI agents, use flags to reduce token usage:++```bash+pinchtab snap -i -c --max-tokens 1000 # Interactive, compact, truncated+pinchtab text --raw # Raw text instead of readability+```++### Error Messages+If server isn't running:+```+β Pinchtab server is not running on http://localhost:9867++To start the server:+ pinchtab # Run in foreground+ pinchtab & # Run in background+```++### Headless vs Headed+```bash+pinchtab # Headless (default, no window)+BRIDGE_HEADLESS=false pinchtab # Headed (visible window)+```++### Profile Management+```bash+BRIDGE_PROFILE=~/.pinchtab/profile1 pinchtab # Custom profile+BRIDGE_NO_RESTORE=true pinchtab # Start fresh+```++---++## Command Reference (Alphabetical)++| Command | Description |+|---------|-------------|+| `click <ref>` | Click element |+| `connect <name>` | Get URL for running profile |+| `dashboard` | Start profile manager |+| `eval <expr>` | Evaluate JavaScript |+| `fill <ref\|selector> <text>` | Set input value |+| `focus <ref>` | Focus element |+| `health` | Check server status |+| `help` | Show help text |+| `hover <ref>` | Hover over element |+| `nav <url>` | Navigate to URL |+| `pdf [-o file]` | Export page as PDF |+| `press <key>` | Press key |+| `quick <url>` | Navigate + analyze (quick start) |+| `screenshot` / `ss` | Take screenshot |+| `scroll <ref\|px>` | Scroll page |+| `select <ref> <val>` | Select dropdown |+| `snap` / `snapshot` | Get accessibility tree |+| `tab[s]` | List/manage tabs |+| `text` | Extract readable text |+| `type <ref> <text>` | Type into element |++---++## Aliases++| Command | Alias |+|---------|-------|+| `nav` | `navigate` |+| `snap` | `snapshot` |+| `ss` | `screenshot` |+| `eval` | `evaluate` |+| `tab` | `tabs` |++---++**For more help:** `pinchtab help`