High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add commands.md reference page
Boschd5d71ea1d93b
diff --git a/cmd/pinchtab/cmd_cli.go b/cmd/pinchtab/cmd_cli.goindex 60ed2419..ffe0cfda 100644--- a/cmd/pinchtab/cmd_cli.go+++ b/cmd/pinchtab/cmd_cli.go@@ -26,7 +26,7 @@ var quickCmd = &cobra.Command{var navCmd = &cobra.Command{Use: "nav <url>",- Aliases: []string{"goto", "navigate"},+ Aliases: []string{"goto", "navigate", "open"},Short: "Navigate to URL",Args: cobra.ExactArgs(1),Run: func(cmd *cobra.Command, args []string) {diff --git a/docs/commands.md b/docs/commands.mdnew file mode 100644index 00000000..0c38e7dc--- /dev/null+++ b/docs/commands.md@@ -0,0 +1,125 @@+# Commands Reference++## Server & Daemon++```+pinchtab server # Start the full server (dashboard + API)+pinchtab bridge # Start bridge-only server (no dashboard)+pinchtab mcp # Start the MCP stdio server+pinchtab daemon # Show daemon status+pinchtab daemon install # Install as background service+pinchtab daemon start # Start the background service+pinchtab daemon stop # Stop the background service+pinchtab daemon restart # Restart the background service+pinchtab daemon uninstall # Remove the background service+```++## Navigation++```+pinchtab nav <url> # Navigate to URL in current tab+pinchtab nav <url> --new-tab # Navigate in a new tab+pinchtab nav <url> --tab <id> # Navigate a specific tab+pinchtab nav <url> --block-images # Navigate with image blocking+pinchtab nav <url> --block-ads # Navigate with ad blocking+pinchtab quick <url> # Navigate + snapshot accessibility tree+```++Hidden aliases: `goto`, `navigate`, `open`++## Tab Management++```+pinchtab tab # List all tabs+pinchtab tab new # Open a new empty tab+pinchtab tab new <url> # Open a new tab with URL+pinchtab tab close <id> # Close a tab+```++Alias: `tabs`++## Interaction++```+pinchtab click <ref> # Click element by ref+pinchtab click --css <selector> # Click element by CSS selector+pinchtab click --wait-nav <ref> # Click and wait for navigation+pinchtab type <ref> <text> # Type into element+pinchtab fill <ref> <text> # Fill input directly (no keystroke events)+pinchtab press <key> # Press key (Enter, Tab, Escape...)+pinchtab hover <ref> # Hover over element+pinchtab hover --css <selector> # Hover by CSS selector+pinchtab select <ref> <value> # Select dropdown option+pinchtab scroll <ref|pixels> # Scroll to element or by pixel amount+```++## Page Analysis++```+pinchtab snap # Snapshot accessibility tree+pinchtab snap --selector <css> # Snapshot scoped to CSS selector+pinchtab snap --role <role> # Filter by ARIA role+pinchtab snap --name <name> # Filter by accessible name+pinchtab text # Extract page text (markdown)+pinchtab text --raw # Extract raw text+pinchtab find <query> # Find elements by natural language+pinchtab eval <expression> # Evaluate JavaScript+```++## Capture & Export++```+pinchtab screenshot # Take a screenshot (PNG)+pinchtab screenshot --format jpeg # Take a JPEG screenshot+pinchtab screenshot --full-page # Full page screenshot+pinchtab screenshot --selector <css> # Screenshot specific element+pinchtab pdf # Export page as PDF+pinchtab pdf --landscape # PDF in landscape orientation+pinchtab pdf --format A3 # PDF with custom paper size+pinchtab download <url> # Download a file+pinchtab download <url> -o path # Download to specific path+pinchtab upload <file> # Upload a file+pinchtab upload <file> -s <css> # Upload to specific file input+```++## Instances & Profiles++```+pinchtab instances # List running instances+pinchtab instance start # Start a new browser instance+pinchtab instance stop <id> # Stop an instance+pinchtab instance logs <id> # View instance logs+pinchtab instance navigate <id> <url> # Navigate instance to URL+pinchtab profiles # List browser profiles+pinchtab health # Check server health+```++## Configuration++```+pinchtab config show # Show current configuration+pinchtab config init # Create default config file+pinchtab config path # Show config file path+pinchtab config validate # Validate config file+pinchtab config get <path> # Get a config value+pinchtab config set <path> <val> # Set a config value+pinchtab config patch <json> # Patch config with JSON+```++## Security++```+pinchtab security # Review security posture+pinchtab security up # Apply recommended security defaults+pinchtab security down # Relax security settings+```++## Global Flags++Most browser commands support `--tab <id>` to target a specific tab.++```+pinchtab <command> --tab <id> # Run command against specific tab+pinchtab --help # Show help+pinchtab --version # Show version+```diff --git a/docs/reference/tabs.md b/docs/reference/tabs.mdindex de1883ea..ba2bd469 100644--- a/docs/reference/tabs.md+++ b/docs/reference/tabs.md@@ -57,7 +57,7 @@ pinchtab instance navigate inst_ea2e747f https://pinchtab.com```bashcurl http://localhost:9867/tabs# CLI Alternative-pinchtab tabs+pinchtab tab# Response{"tabs": [@@ -75,7 +75,7 @@ Notes:- `GET /tabs` is not a fleet-wide orchestrator inventory- in bridge mode or shorthand mode it lists tabs from the active browser context-- `pinchtab tabs` follows that shorthand behavior+- `pinchtab tab` follows that shorthand behavior### One Instancediff --git a/tests/e2e/scenarios-cli/04-tabs.sh b/tests/e2e/scenarios-cli/04-tabs.shindex 15b11320..1ca842bf 100755--- a/tests/e2e/scenarios-cli/04-tabs.sh+++ b/tests/e2e/scenarios-cli/04-tabs.sh@@ -4,7 +4,7 @@source "$(dirname "$0")/common.sh"# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs (list)"+start_test "pinchtab tab (list)"# Create a tab firstpt_ok nav "${FIXTURES_URL}/index.html"@@ -16,7 +16,7 @@ assert_output_contains "tabs" "returns tabs array"end_test# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs close <id>"+start_test "pinchtab tab close <id>"pt_ok nav "${FIXTURES_URL}/form.html"TAB_ID=$(echo "$PT_OUT" | jq -r '.tabId')diff --git a/tests/e2e/scenarios-cli/14-tabs-new.sh b/tests/e2e/scenarios-cli/14-tabs-new.shindex ab8596f0..6e8b61d2 100755--- a/tests/e2e/scenarios-cli/14-tabs-new.sh+++ b/tests/e2e/scenarios-cli/14-tabs-new.sh@@ -4,9 +4,9 @@source "$(dirname "$0")/common.sh"# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs new <url>"+start_test "pinchtab tab new <url>"-pt_ok tabs new "${FIXTURES_URL}/buttons.html"+pt_ok tab new "${FIXTURES_URL}/buttons.html"assert_output_jsonassert_output_contains "tabId" "returns new tab ID"@@ -14,7 +14,7 @@ assert_output_contains "tabId" "returns new tab ID"NEW_TAB_ID=$(echo "$PT_OUT" | jq -r '.tabId')# Verify it appears in tabs list-pt_ok tabs+pt_ok tabassert_output_contains "$NEW_TAB_ID" "new tab appears in list"# Cleanupdiff --git a/tests/e2e/scenarios-cli/17-tabs-ops.sh b/tests/e2e/scenarios-cli/17-tabs-ops.shindex b0874719..79607346 100755--- a/tests/e2e/scenarios-cli/17-tabs-ops.sh+++ b/tests/e2e/scenarios-cli/17-tabs-ops.sh@@ -4,10 +4,10 @@source "$(dirname "$0")/common.sh"# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs (list)"+start_test "pinchtab tab (list)"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok tabs+pt_ok tabassert_output_jsonend_testdiff --git a/tests/e2e/scenarios-cli/22-tabs-errors.sh b/tests/e2e/scenarios-cli/22-tabs-errors.shindex c19f9ee3..33bd44f0 100755--- a/tests/e2e/scenarios-cli/22-tabs-errors.sh+++ b/tests/e2e/scenarios-cli/22-tabs-errors.sh@@ -4,7 +4,7 @@source "$(dirname "$0")/common.sh"# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs returns valid JSON array"+start_test "pinchtab tab returns valid JSON array"pt_ok tabassert_output_json "tabs output is valid JSON"@@ -13,7 +13,7 @@ assert_output_contains "tabs" "response contains tabs field"end_test# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs new + close roundtrip"+start_test "pinchtab tab new + close roundtrip"# Use nav to create a tab in the existing instance (returns tabId reliably)pt_ok nav "${FIXTURES_URL}/index.html"@@ -29,14 +29,14 @@ assert_output_not_contains "$TAB_ID" "closed tab no longer in list"end_test# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs close with no args → error"+start_test "pinchtab tab close with no args → error"pt_fail tab closeend_test# ─────────────────────────────────────────────────────────────────-start_test "pinchtab tabs close nonexistent → error"+start_test "pinchtab tab close nonexistent → error"pt_fail tab close "nonexistent_tab_id_12345"