Skip to content

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

fix: instances/profiles output human-readable by default

Luigi Agostie6e1fd3fdd06
diff --git a/cmd/pinchtab/cmd_cli_management.go b/cmd/pinchtab/cmd_cli_management.go
index ec272404..612b412e 100644
--- a/cmd/pinchtab/cmd_cli_management.go
+++ b/cmd/pinchtab/cmd_cli_management.go
@@ -11,7 +11,7 @@ var instancesCmd = &cobra.Command{
Short: "List or manage instances",
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
- browseractions.Instances(rt.client, rt.base, rt.token)
+ browseractions.Instances(rt.client, rt.base, rt.token, cmd)
})
},
}
@@ -31,7 +31,7 @@ var profilesCmd = &cobra.Command{
Short: "List browser profiles",
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
- browseractions.Profiles(rt.client, rt.base, rt.token)
+ browseractions.Profiles(rt.client, rt.base, rt.token, cmd)
})
},
}
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 83b21df0..154a5391 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -348,6 +348,9 @@ func configureManagementFlags() {
activityCmd.PersistentFlags().Int("limit", 200, "Maximum number of events to return")
activityCmd.PersistentFlags().Int("age-sec", 0, "Only include events from the last N seconds")
+
+ instancesCmd.Flags().Bool("json", false, "Output full JSON response instead of terse status")
+ profilesCmd.Flags().Bool("json", false, "Output full JSON response instead of terse status")
}
func setCommandGroup(groupID string, cmds ...*cobra.Command) {
diff --git a/docs/reference/cache.md b/docs/reference/cache.md
index 44885d4a..f76c8722 100644
--- a/docs/reference/cache.md
+++ b/docs/reference/cache.md
@@ -6,24 +6,32 @@ Clear the browser's HTTP disk cache.
```bash
curl -X POST http://localhost:9867/cache/clear
-# CLI Alternative
-pinchtab cache clear
# Response
{
"status": "cleared"
}
+
+# CLI Alternative (human-readable by default)
+pinchtab cache clear
+# Output: OK
+
+pinchtab cache clear --json # Full JSON response
```
## Check Status
```bash
curl http://localhost:9867/cache/status
-# CLI Alternative
-pinchtab cache status
# Response
{
"canClear": true
}
+
+# CLI Alternative (human-readable by default)
+pinchtab cache status
+# Output: can-clear (or cache-empty)
+
+pinchtab cache status --json # Full JSON response
```
## Notes
diff --git a/docs/reference/health.md b/docs/reference/health.md
index 6d8bfa36..04820ff6 100644
--- a/docs/reference/health.md
+++ b/docs/reference/health.md
@@ -6,13 +6,13 @@ Check server status and availability.
```bash
curl http://localhost:9867/health
-# CLI Alternative
+# Response: {"status":"ok","tabs":1}
+
+# CLI Alternative (human-readable by default)
pinchtab health
-# Response
-{
- "status": "ok",
- "tabs": 1
-}
+# Output: ok
+
+pinchtab health --json # Full JSON response
```
Bridge-mode health may also include:
diff --git a/docs/reference/instances.md b/docs/reference/instances.md
index 59996a05..876c079d 100644
--- a/docs/reference/instances.md
+++ b/docs/reference/instances.md
@@ -14,8 +14,13 @@ One profile can have at most one active managed instance at a time.
```bash
curl http://localhost:9867/instances
-# CLI Alternative
+# Response: JSON array (see below)
+
+# CLI Alternative (human-readable by default)
pinchtab instances
+# Output: inst_0a89 9999 headed running
+
+pinchtab instances --json # Full JSON response
```
`pinchtab instances` is the simplest way to inspect the current fleet from the CLI.
diff --git a/docs/reference/pdf.md b/docs/reference/pdf.md
index 98c1c83b..5dc4676c 100644
--- a/docs/reference/pdf.md
+++ b/docs/reference/pdf.md
@@ -4,13 +4,13 @@ Render the current page as a PDF.
```bash
curl "http://localhost:9867/pdf?output=file"
-# CLI Alternative
+# Response: {"path":"/path/to/state/pdfs/page-20260308-120001.pdf","size":48210}
+
+# CLI Alternative (human-readable by default)
pinchtab pdf -o page.pdf
-# Response
-{
- "path": "/path/to/state/pdfs/page-20260308-120001.pdf",
- "size": 48210
-}
+# Output: Saved page.pdf (48210 bytes)
+
+pinchtab pdf # Auto-generates filename: page-20260308-120001.pdf
```
## CLI Flags
diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md
index 3419612b..c51d0b86 100644
--- a/docs/reference/profiles.md
+++ b/docs/reference/profiles.md
@@ -12,9 +12,20 @@ In PinchTab:
```bash
curl http://localhost:9867/profiles
-# CLI Alternative
+# Response: JSON array (see below)
+
+# CLI Alternative (human-readable by default)
pinchtab profiles
-# Response
+# Output: prof_278be873 work
+
+pinchtab profiles --json # Full JSON response
+```
+
+`pinchtab profiles` is the simplest way to see available profiles from the CLI.
+
+Response shape:
+
+```json
[
{
"id": "prof_278be873",
@@ -34,7 +45,6 @@ Notes:
- `GET /profiles` excludes temporary auto-generated instance profiles by default
- use `GET /profiles?all=true` to include temporary profiles
-- `pinchtab profiles` exists, but the HTTP API is the more reliable source of truth for structured output
## Get One Profile
diff --git a/docs/reference/scroll.md b/docs/reference/scroll.md
index 08a377f2..4b5064ce 100644
--- a/docs/reference/scroll.md
+++ b/docs/reference/scroll.md
@@ -6,17 +6,15 @@ Scroll the current tab or a specific element.
curl -X POST http://localhost:9867/action \
-H "Content-Type: application/json" \
-d '{"kind":"scroll","scrollY":800}'
-# CLI Alternative
+# Response: {"success":true,"result":{"success":true}}
+
+# CLI Alternative (human-readable by default)
pinchtab scroll down
+# Output: OK
+
pinchtab scroll down --snap # scroll and output snapshot
pinchtab scroll 800 --snap-diff # scroll and output snapshot diff
-# Response
-{
- "success": true,
- "result": {
- "success": true
- }
-}
+pinchtab scroll 800 --json # Full JSON response
```
Notes:
diff --git a/internal/cli/actions/actions_system.go b/internal/cli/actions/actions_system.go
index be65fa09..405a773e 100644
--- a/internal/cli/actions/actions_system.go
+++ b/internal/cli/actions/actions_system.go
@@ -8,7 +8,6 @@ import (
"net/http"
"os"
- "github.com/pinchtab/pinchtab/internal/cli"
"github.com/pinchtab/pinchtab/internal/cli/apiclient"
"github.com/pinchtab/pinchtab/internal/cli/output"
"github.com/spf13/cobra"
@@ -41,7 +40,13 @@ func Health(client *http.Client, base, token string, cmd *cobra.Command) {
}
}
-func Instances(client *http.Client, base, token string) {
+func Instances(client *http.Client, base, token string, cmd *cobra.Command) {
+ jsonOutput, _ := cmd.Flags().GetBool("json")
+ if jsonOutput {
+ apiclient.DoGet(client, base, token, "/instances", nil)
+ return
+ }
+
body := apiclient.DoGetRaw(client, base, token, "/instances", nil)
instances, err := decodeInstancesResponse(body)
@@ -50,9 +55,13 @@ func Instances(client *http.Client, base, token string) {
os.Exit(1)
}
- // Transform to cleaner output format
- output := make([]map[string]any, len(instances))
- for i, inst := range instances {
+ if len(instances) == 0 {
+ fmt.Println("No instances running")
+ return
+ }
+
+ // Human-readable: id port mode status
+ for _, inst := range instances {
id, _ := inst["id"].(string)
port, _ := inst["port"].(string)
headless, _ := inst["headless"].(bool)
@@ -63,38 +72,45 @@ func Instances(client *http.Client, base, token string) {
mode = "headed"
}
- output[i] = map[string]any{
- "id": id,
- "port": port,
- "mode": mode,
- "status": status,
- }
+ fmt.Printf("%s\t%s\t%s\t%s\n", id, port, mode, status)
}
-
- // Output as JSON
- data, _ := json.MarshalIndent(output, "", " ")
- fmt.Println(string(data))
}
// --- profiles ---
-func Profiles(client *http.Client, base, token string) {
- result := apiclient.DoGet(client, base, token, "/profiles", nil)
+func Profiles(client *http.Client, base, token string, cmd *cobra.Command) {
+ jsonOutput, _ := cmd.Flags().GetBool("json")
+ if jsonOutput {
+ apiclient.DoGet(client, base, token, "/profiles", nil)
+ return
+ }
+
+ body := apiclient.DoGetRaw(client, base, token, "/profiles", nil)
- // Display profiles in a friendly format
- if profiles, ok := result["profiles"].([]interface{}); ok && len(profiles) > 0 {
- fmt.Println()
- for _, prof := range profiles {
- if m, ok := prof.(map[string]any); ok {
- name, _ := m["name"].(string)
+ profiles, err := decodeProfilesResponse(body)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Failed to parse profiles: %v\n", err)
+ os.Exit(1)
+ }
- fmt.Printf("%s %s\n", cli.StyleStdout(cli.ValueStyle, "profile:"), name)
- }
- }
- fmt.Println()
- } else {
+ if len(profiles) == 0 {
fmt.Println("No profiles available")
+ return
+ }
+
+ for _, prof := range profiles {
+ id, _ := prof["id"].(string)
+ name, _ := prof["name"].(string)
+ fmt.Printf("%s\t%s\n", id, name)
+ }
+}
+
+func decodeProfilesResponse(body []byte) ([]map[string]any, error) {
+ var profiles []map[string]any
+ if err := json.Unmarshal(body, &profiles); err == nil {
+ return profiles, nil
}
+ return nil, fmt.Errorf("expected /profiles to return a JSON array")
}
// --- internal helpers ---
diff --git a/tests/e2e/scenarios/cli/browser-basic.sh b/tests/e2e/scenarios/cli/browser-basic.sh
index 401c96c1..ade298c9 100644
--- a/tests/e2e/scenarios/cli/browser-basic.sh
+++ b/tests/e2e/scenarios/cli/browser-basic.sh
@@ -16,7 +16,7 @@ end_test
# ─────────────────────────────────────────────────────────────────
start_test "pinchtab instances"
-pt_ok instances
+pt_ok instances --json
assert_output_json
# Output is an array like [{id:..., status:...}], check for instance properties
assert_output_contains "id" "returns instance id"