Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: fix tabs.md lock/unlock CLI references and clarify GET /tabs/{id}

Bosch6535896e2377
diff --git a/docs/reference/instances.md b/docs/reference/instances.md
index 565b2d9b..d5ef9364 100644
--- a/docs/reference/instances.md
+++ b/docs/reference/instances.md
@@ -37,9 +37,9 @@ pinchtab instances
```bash
curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"profileId":"278be873adeb","mode":"headed","port":"9999"}'
+ -d '{"profileId":"prof_278be873","mode":"headed","port":"9999"}'
# CLI Alternative
-pinchtab instance start --profileId 278be873adeb --mode headed --port 9999
+pinchtab instance start --profileId prof_278be873 --mode headed --port 9999
# Response
{
"id": "inst_ea2e747f",
@@ -113,7 +113,7 @@ Stopping an instance preserves the profile unless it was a temporary auto-genera
You can also start an instance from a profile-oriented route:
```bash
-curl -X POST http://localhost:9867/profiles/278be873adeb/start \
+curl -X POST http://localhost:9867/profiles/prof_278be873/start \
-H "Content-Type: application/json" \
-d '{"headless":false,"port":"9999"}'
# Response
diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md
index 01498bbd..d8f13080 100644
--- a/docs/reference/profiles.md
+++ b/docs/reference/profiles.md
@@ -17,7 +17,7 @@ pinchtab profiles
# Response
[
{
- "id": "278be873adeb",
+ "id": "prof_278be873",
"name": "work",
"created": "2026-02-27T20:37:13.599055326Z",
"diskUsage": 534952089,
@@ -39,10 +39,10 @@ Notes:
## Get One Profile
```bash
-curl http://localhost:9867/profiles/278be873adeb
+curl http://localhost:9867/profiles/prof_278be873
# Response
{
- "id": "278be873adeb",
+ "id": "prof_278be873",
"name": "work",
"path": "/path/to/profiles/work",
"pathExists": true,
@@ -70,23 +70,26 @@ curl -X POST http://localhost:9867/profiles \
# Response
{
"status": "created",
- "id": "0f32ae81e4a1",
+ "id": "prof_0f32ae81",
"name": "scraping-profile"
}
```
-There is no `pinchtab profile create` CLI command today.
+Notes:
+
+- there is no `pinchtab profile create` CLI command
+- both `POST /profiles` and `POST /profiles/create` work for creating profiles
## Update A Profile
```bash
-curl -X PATCH http://localhost:9867/profiles/278be873adeb \
+curl -X PATCH http://localhost:9867/profiles/prof_278be873 \
-H "Content-Type: application/json" \
-d '{"description":"Updated description","useWhen":"Updated usage note"}'
# Response
{
"status": "updated",
- "id": "278be873adeb",
+ "id": "prof_278be873",
"name": "work"
}
```
@@ -94,7 +97,7 @@ curl -X PATCH http://localhost:9867/profiles/278be873adeb \
You can also rename the profile:
```bash
-curl -X PATCH http://localhost:9867/profiles/278be873adeb \
+curl -X PATCH http://localhost:9867/profiles/prof_278be873 \
-H "Content-Type: application/json" \
-d '{"name":"work-renamed"}'
```
@@ -108,11 +111,11 @@ Important:
## Delete A Profile
```bash
-curl -X DELETE http://localhost:9867/profiles/278be873adeb
+curl -X DELETE http://localhost:9867/profiles/prof_278be873
# Response
{
"status": "deleted",
- "id": "278be873adeb",
+ "id": "prof_278be873",
"name": "work"
}
```
@@ -124,13 +127,13 @@ curl -X DELETE http://localhost:9867/profiles/278be873adeb
Start the active instance for a profile:
```bash
-curl -X POST http://localhost:9867/profiles/278be873adeb/start \
+curl -X POST http://localhost:9867/profiles/prof_278be873/start \
-H "Content-Type: application/json" \
-d '{"headless":true}'
# Response
{
"id": "inst_ea2e747f",
- "profileId": "278be873adeb",
+ "profileId": "prof_278be873",
"profileName": "work",
"port": "9868",
"headless": true,
@@ -141,11 +144,11 @@ curl -X POST http://localhost:9867/profiles/278be873adeb/start \
Stop the active instance for a profile:
```bash
-curl -X POST http://localhost:9867/profiles/278be873adeb/stop
+curl -X POST http://localhost:9867/profiles/prof_278be873/stop
# Response
{
"status": "stopped",
- "id": "278be873adeb",
+ "id": "prof_278be873",
"name": "work"
}
```
@@ -155,7 +158,7 @@ For these orchestrator routes, the path can be a profile ID or profile name.
## Check Whether A Profile Has A Running Instance
```bash
-curl http://localhost:9867/profiles/278be873adeb/instance
+curl http://localhost:9867/profiles/prof_278be873/instance
# Response
{
"name": "work",
@@ -171,7 +174,7 @@ curl http://localhost:9867/profiles/278be873adeb/instance
### Reset A Profile
```bash
-curl -X POST http://localhost:9867/profiles/278be873adeb/reset
+curl -X POST http://localhost:9867/profiles/prof_278be873/reset
```
This route requires the profile ID.
@@ -187,7 +190,7 @@ curl -X POST http://localhost:9867/profiles/import \
### Get Logs
```bash
-curl http://localhost:9867/profiles/278be873adeb/logs
+curl http://localhost:9867/profiles/prof_278be873/logs
curl 'http://localhost:9867/profiles/work/logs?limit=50'
```
@@ -196,7 +199,7 @@ curl 'http://localhost:9867/profiles/work/logs?limit=50'
### Get Analytics
```bash
-curl http://localhost:9867/profiles/278be873adeb/analytics
+curl http://localhost:9867/profiles/prof_278be873/analytics
curl http://localhost:9867/profiles/work/analytics
```
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index cf7c53cd..de1883ea 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -204,20 +204,38 @@ This returns aggregate browser metrics for the tab's owning instance, not isolat
## Lock And Unlock
+Tab lock/unlock is **API-only** — no CLI commands exist yet.
+
+### Lock A Specific Tab
+
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/lock \
-H "Content-Type: application/json" \
-d '{"owner":"my-agent","ttl":60}'
-# CLI Alternative
-pinchtab tab lock <tabId> --owner my-agent --ttl 60
```
+### Lock The Active Tab
+
+```bash
+curl -X POST http://localhost:9867/tab/lock \
+ -H "Content-Type: application/json" \
+ -d '{"owner":"my-agent","ttl":60}'
+```
+
+### Unlock A Specific Tab
+
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/unlock \
-H "Content-Type: application/json" \
-d '{"owner":"my-agent"}'
-# CLI Alternative
-pinchtab tab unlock <tabId> --owner my-agent
+```
+
+### Unlock The Active Tab
+
+```bash
+curl -X POST http://localhost:9867/tab/unlock \
+ -H "Content-Type: application/json" \
+ -d '{"owner":"my-agent"}'
```
## Close A Tab
@@ -234,6 +252,5 @@ pinchtab tab close <tabId>
## Important Limits
-- there is no documented `GET /tabs/{id}` resource endpoint in the current server routes
-- `pinchtab tab info <tabId>` exists in the CLI, but it depends on a route that is not part of the current documented HTTP surface
+- **There is no `GET /tabs/{id}` endpoint** for fetching single tab info. Use `GET /tabs` to list all tabs or access tab-scoped sub-paths like `/tabs/{id}/snapshot`, `/tabs/{id}/action`, etc.
- `GET /tabs` and `GET /instances/tabs` serve different purposes and should not be treated as interchangeable
diff --git a/tests/e2e/scenarios-cli/18-tabs-lock.sh b/tests/e2e/scenarios-cli/18-tabs-lock.sh
deleted file mode 100755
index 605c2540..00000000
--- a/tests/e2e/scenarios-cli/18-tabs-lock.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/bash
-# 18-tabs-lock.sh — Tab locking operations
-
-source "$(dirname "$0")/common.sh"
-
-# SKIP: tabs lock/unlock not yet implemented in cobra CLI refactor
-# See: feat/cli-update branch
-# start_test "pinchtab tabs lock/unlock <tabId>"
-# pt_ok nav "${FIXTURES_URL}/index.html"
-# TAB_ID=$(echo "$PT_OUT" | jq -r '.tabId')
-# pt_ok tabs lock "$TAB_ID" --owner "test-suite"
-# pt_ok tabs unlock "$TAB_ID" --owner "test-suite"
-# end_test
diff --git a/tests/e2e/scenarios-cli/32-security.sh b/tests/e2e/scenarios-cli/32-security.sh
new file mode 100755
index 00000000..8dd20b06
--- /dev/null
+++ b/tests/e2e/scenarios-cli/32-security.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+# 32-security.sh — CLI security commands
+
+source "$(dirname "$0")/common.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab security (non-interactive)"
+
+# In non-interactive mode (piped), should show security posture and exit
+pt security
+
+# Security may exit 0 or non-zero depending on posture, just verify it runs without crashing
+if [ -n "$PT_OUT" ] || [ "$PT_CODE" -eq 0 ] || [ "$PT_CODE" -ne 0 ]; then
+ echo -e " ${GREEN}✓${NC} security command executed (exit code: $PT_CODE)"
+ ((ASSERTIONS_PASSED++)) || true
+else
+ echo -e " ${RED}✗${NC} security command failed unexpectedly"
+ ((ASSERTIONS_FAILED++)) || true
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab security up"
+
+pt_ok security up
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab security down"
+
+pt_ok security down
+
+end_test
diff --git a/tests/e2e/scenarios/35-profile-rename.sh b/tests/e2e/scenarios/35-profile-rename.sh
index 12d5866d..d97af2c0 100755
--- a/tests/e2e/scenarios/35-profile-rename.sh
+++ b/tests/e2e/scenarios/35-profile-rename.sh
@@ -130,3 +130,20 @@ for NAME in "e2e-valid-1" "e2e_valid_2" "e2eVALID3"; do
done
end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "profile reset"
+
+# Create a profile
+pt_post /profiles -d '{"name":"reset-test-profile"}'
+assert_ok "create profile for reset"
+PROFILE_ID=$(echo "$RESULT" | jq -r '.id')
+
+# Reset it
+pt_post "/profiles/${PROFILE_ID}/reset" ""
+assert_ok "reset profile"
+
+# Clean up
+pt_delete "/profiles/${PROFILE_ID}"
+
+end_test