Skip to content

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.go
index 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.md
new file mode 100644
index 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.md
index 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
```bash
curl 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 Instance
diff --git a/tests/e2e/scenarios-cli/04-tabs.sh b/tests/e2e/scenarios-cli/04-tabs.sh
index 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 first
pt_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.sh
index 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_json
assert_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 tab
assert_output_contains "$NEW_TAB_ID" "new tab appears in list"
# Cleanup
diff --git a/tests/e2e/scenarios-cli/17-tabs-ops.sh b/tests/e2e/scenarios-cli/17-tabs-ops.sh
index 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 tab
assert_output_json
end_test
diff --git a/tests/e2e/scenarios-cli/22-tabs-errors.sh b/tests/e2e/scenarios-cli/22-tabs-errors.sh
index 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 tab
assert_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 close
end_test
# ─────────────────────────────────────────────────────────────────
-start_test "pinchtab tabs close nonexistent → error"
+start_test "pinchtab tab close nonexistent → error"
pt_fail tab close "nonexistent_tab_id_12345"