CLI Overview

pinchtab has two normal usage styles:

  • interactive menu mode
  • direct command mode

Use the menu when you want a guided local control surface. Use direct commands when you want shell history, scripts, or remote targeting with --server.

When you target a remote server with --server, the CLI is exercising the same privileged control plane as the dashboard and HTTP API. Do not use it as an access path for untrusted users or untrusted systems. For deployment guidance, see Security.

Interactive Menu

Running pinchtab with no subcommand in an interactive terminal opens the menu. It does not immediately start the server.

Typical flow:

listen    running  127.0.0.1:9867
str,plc   simple,fcfs
daemon    ok
security  [■■■■■■■■■■]  LOCKED

Main Menu
  1. Start server
  2. Daemon
  3. Start bridge
  4. Start MCP server
  5. Config
  6. Security
  7. Help
  8. Exit

Direct Commands

Use direct commands when you already know the action you want:

terminal 
pinchtab serverpinchtab bridgepinchtab mcppinchtab configpinchtab --agent-id agent-main nav https://pinchtab.compinchtab nav https://pinchtab.compinchtab snap -i -cpinchtab click e5pinchtab find "login button"pinchtab network --limit 20
pinchtab serverpinchtab bridgepinchtab mcppinchtab configpinchtab --agent-id agent-main nav https://pinchtab.compinchtab nav https://pinchtab.compinchtab snap -i -cpinchtab click e5pinchtab find "login button"pinchtab network --limit 20

Global flags such as --server and --agent-id apply to direct command mode. --agent-id is recorded in activity logs and dashboard agent views so multiple CLI-driven agents are distinguishable.

Agent Attribution

CLI requests carry agent identity over the X-Agent-Id request header.

  • --agent-id <value> sets the header explicitly for that command
  • PINCHTAB_AGENT_ID sets the default agent ID for the current shell or script
  • if neither is set, the CLI uses cli

That agent ID is what appears as agentId in /api/activity, the Agents page, and scheduler-driven activity.

Example:

terminal 
PINCHTAB_AGENT_ID=agent-crawl-01 pinchtab nav https://pinchtab.comcurl 'http://127.0.0.1:9867/api/activity?agentId=agent-crawl-01'
PINCHTAB_AGENT_ID=agent-crawl-01 pinchtab nav https://pinchtab.comcurl 'http://127.0.0.1:9867/api/activity?agentId=agent-crawl-01'

Output Format

Most commands output human-readable text by default. Use --json for structured output:

terminal 
pinchtab tab                  # *abc123  https://...  Titlepinchtab tab --json           # {"tabs":[...]}pinchtab frame                # mainpinchtab network              # GET  200  https://...
pinchtab tab                  # *abc123  https://...  Titlepinchtab tab --json           # {"tabs":[...]}pinchtab frame                # mainpinchtab network              # GET  200  https://...

For scripts: Always use --json when piping or parsing programmatically. Human-readable output may change between versions. JSON is the stable contract.

Core Commands

CommandPurpose
pinchtab serverStart the full server and dashboard
pinchtab bridgeStart the single-instance bridge runtime
pinchtab mcpStart the stdio MCP server
pinchtab daemonShow daemon status and manage the background service
pinchtab configOpen the interactive config overview/editor
pinchtab securityOpen the interactive security overview
pinchtab completion <shell>Generate shell completion scripts

Browser Commands

The browser control surface is top-level. tab is only for list/focus/new/close.

Common commands:

CommandPurpose
pinchtab nav <url>Open a new tab and navigate it
pinchtab quick <url>Navigate and snapshot
pinchtab snapAccessibility snapshot
pinchtab frame [target|main]Show or set selector frame scope
pinchtab click <selector>Click an element
pinchtab mouse move <x> <y>Move the pointer to coordinates
pinchtab mouse down [selector]Press a mouse button at the current pointer or a fresh target
pinchtab mouse up [selector]Release a mouse button at the current pointer or a fresh target
pinchtab mouse wheel [dy|selector]Dispatch wheel deltas at the current pointer or a fresh target
pinchtab drag <from> <to>Drag from one target to another
pinchtab type <selector> <text>Type via key events
pinchtab fill <selector> <text>Fill directly
pinchtab textExtract page text (--full, --raw, --frame <frameId>)
pinchtab find <query>Semantic element search
pinchtab screenshotSave a screenshot (-s/--selector captures a specific element, --css-1x exports selector shots at CSS size)
pinchtab pdfExport the page as PDF
pinchtab networkInspect captured network requests
pinchtab wait ...Wait for selector, text, URL, JS, or time
pinchtab consoleShow browser console logs
pinchtab errorsShow browser error logs

Many browser commands accept --tab <id> to target an existing tab instead of the active one.

Selector lookup is explicit by frame. Unscoped selectors stay in the main document unless you set a frame first with pinchtab frame. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.

pinchtab text follows that frame model too: it uses the active frame scope unless you override it with --frame.

pinchtab eval is separate from that model and does not inherit current frame scope.

Selector-based actions fail fast when a selector does not match. If you expect dynamic content to appear shortly, use pinchtab wait first.

Manual handoff is currently API-only:

This is currently advisory state only. It marks the tab as paused_handoff, but it does not yet provide a guaranteed blocking pause for later automation.

terminal 
curl -X POST http://localhost:9867/tabs/<tabId>/handoff \  -H "Content-Type: application/json" \  -d '{"reason":"captcha"}'curl http://localhost:9867/tabs/<tabId>/handoffcurl -X POST http://localhost:9867/tabs/<tabId>/resume \  -H "Content-Type: application/json" \  -d '{"status":"completed"}'
curl -X POST http://localhost:9867/tabs/<tabId>/handoff \  -H "Content-Type: application/json" \  -d '{"reason":"captcha"}'curl http://localhost:9867/tabs/<tabId>/handoffcurl -X POST http://localhost:9867/tabs/<tabId>/resume \  -H "Content-Type: application/json" \  -d '{"status":"completed"}'

Tab Command

pinchtab tab is intentionally small:

terminal 
pinchtab tabpinchtab tab <id>pinchtab tab new [url]pinchtab tab close <id>
pinchtab tabpinchtab tab <id>pinchtab tab new [url]pinchtab tab close <id>

For tab-scoped actions, use the normal top-level command with --tab:

terminal 
pinchtab click --tab <id> e5pinchtab pdf --tab <id> -o page.pdf
pinchtab click --tab <id> e5pinchtab pdf --tab <id> -o page.pdf

Config From The CLI

pinchtab config shows:

  • multiInstance.strategy
  • multiInstance.allocationPolicy
  • instanceDefaults.stealthLevel
  • instanceDefaults.tabEvictionPolicy
  • the active config file path
  • the dashboard URL when the server is running
  • the masked server token
  • a Copy token action

For file schema details and config get/set/patch, see Config.

Security From The CLI

pinchtab security is the interactive security screen.

Direct subcommands:

terminal 
pinchtab security uppinchtab security down
pinchtab security uppinchtab security down

pinchtab security down applies the documented, non-default, security-reducing preset for local operator workflows. It is not the baseline security posture.

For broader security guidance, see Security Guide.

Daemon

pinchtab daemon supports:

  • macOS via launchd
  • Linux via user systemd

Windows binaries exist, but daemon workflows are not currently supported there. Use pinchtab server or pinchtab bridge directly.

For operational details, see Background Service (Daemon).

Full Command Tree

Use built-in help for the live command tree:

terminal 
pinchtab --help
pinchtab --help

For per-command pages, start at Reference Index.