Skip to content

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

fix(cli): give instance its own list subcommand and print arg errors once

Luigi Agosti22eb3209bbff
diff --git a/cmd/pinchtab/cmd_cli_instance_test.go b/cmd/pinchtab/cmd_cli_instance_test.go
new file mode 100644
index 00000000..4abd18c5
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_instance_test.go
@@ -0,0 +1,139 @@
+package main
+
+import (
+ "bytes"
+ "strings"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/cli"
+ "github.com/spf13/cobra"
+)
+
+func instanceSubcommand(t *testing.T, name string) *cobra.Command {
+ t.Helper()
+ for _, sub := range instanceCmd.Commands() {
+ if sub.Name() == name {
+ return sub
+ }
+ }
+ t.Fatalf("pinchtab instance has no %q subcommand; its subcommands are %v", name, instanceSubcommandNames())
+ return nil
+}
+
+func instanceSubcommandNames() []string {
+ var names []string
+ for _, sub := range instanceCmd.Commands() {
+ names = append(names, sub.Name())
+ }
+ return names
+}
+
+func TestInstanceOwnsTheListing(t *testing.T) {
+ list := instanceSubcommand(t, "list")
+ if list.Run == nil {
+ t.Error("pinchtab instance list has no Run, so the listing is registered but does nothing")
+ }
+ if list.Hidden {
+ t.Error("pinchtab instance list is hidden, so the command that produces instance ids stays undiscoverable")
+ }
+}
+
+func TestInstancesStaysRunnableAsADeprecatedAlias(t *testing.T) {
+ if instancesCmd.Run == nil {
+ t.Fatal("pinchtab instances no longer runs; existing scripts and docs calling it would break")
+ }
+ if instancesCmd.Deprecated == "" {
+ t.Error("pinchtab instances is not marked deprecated, so nothing steers callers to the canonical spelling")
+ }
+ if !strings.Contains(instancesCmd.Deprecated, "pinchtab instance list") {
+ t.Errorf("the deprecation notice does not name the replacement: %q", instancesCmd.Deprecated)
+ }
+ if !instancesCmd.Hidden {
+ t.Error("pinchtab instances is still listed at the root, which keeps two commands one character apart for the same subject")
+ }
+}
+
+func TestInstanceIDErrorsNameTheListCommand(t *testing.T) {
+ for _, name := range []string{"logs", "stop", "restart", "navigate"} {
+ t.Run(name, func(t *testing.T) {
+ sub := instanceSubcommand(t, name)
+ if sub.Args == nil {
+ t.Fatalf("pinchtab instance %s has no Args validator", name)
+ }
+ err := sub.Args(sub, nil)
+ if err == nil {
+ t.Fatalf("pinchtab instance %s accepted zero arguments", name)
+ }
+ if !strings.Contains(err.Error(), "pinchtab instance list") {
+ t.Errorf("pinchtab instance %s reports %q; an operator told they need an id is not told where ids come from", name, err)
+ }
+ })
+ }
+}
+
+func TestInstanceIDValidatorAcceptsTheRightArity(t *testing.T) {
+ if err := instanceSubcommand(t, "logs").Args(instanceLogsCmd, []string{"inst_1"}); err != nil {
+ t.Errorf("logs rejected a single id: %v", err)
+ }
+ if err := instanceSubcommand(t, "navigate").Args(instanceNavigateCmd, []string{"inst_1", "https://example.com"}); err != nil {
+ t.Errorf("navigate rejected an id plus a URL: %v", err)
+ }
+ if err := instanceSubcommand(t, "navigate").Args(instanceNavigateCmd, []string{"inst_1"}); err == nil {
+ t.Error("navigate accepted an id with no URL")
+ }
+}
+
+// The usage template renders one shared block for every command, so a heading
+// with nothing under it appears on every leaf command in the CLI, not just the
+// one it was reported against.
+func TestUsageOmitsTheCommandsHeadingWhenThereAreNoSubcommands(t *testing.T) {
+ root := &cobra.Command{Use: "root"}
+ leaf := &cobra.Command{Use: "leaf", Short: "a leaf", Run: func(*cobra.Command, []string) {}}
+ parent := &cobra.Command{Use: "parent", Short: "a parent"}
+ parent.AddCommand(&cobra.Command{Use: "child", Short: "a child", Run: func(*cobra.Command, []string) {}})
+ root.AddCommand(leaf, parent)
+ cli.SetupUsage(root)
+
+ var leafOut bytes.Buffer
+ leaf.SetOut(&leafOut)
+ if err := leaf.Usage(); err != nil {
+ t.Fatal(err)
+ }
+ if strings.Contains(leafOut.String(), "Commands") {
+ t.Errorf("a command with no subcommands still renders a Commands heading with nothing under it:\n%s", leafOut.String())
+ }
+
+ var parentOut bytes.Buffer
+ parent.SetOut(&parentOut)
+ if err := parent.Usage(); err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(parentOut.String(), "Commands") {
+ t.Errorf("a command with subcommands lost its Commands heading:\n%s", parentOut.String())
+ }
+ if !strings.Contains(parentOut.String(), "child") {
+ t.Errorf("subcommands are no longer listed:\n%s", parentOut.String())
+ }
+}
+
+func TestExecutePrintsAnErrorOnlyWhenCobraDidNot(t *testing.T) {
+ root := &cobra.Command{Use: "root"}
+ for _, tc := range []struct {
+ name string
+ cmd *cobra.Command
+ rootSilent bool
+ want bool
+ }{
+ {"cobra printed it", &cobra.Command{Use: "c"}, false, false},
+ {"command silenced it", &cobra.Command{Use: "c", SilenceErrors: true}, false, true},
+ {"root silenced it", &cobra.Command{Use: "c"}, true, true},
+ {"no command resolved", nil, false, true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ root.SilenceErrors = tc.rootSilent
+ if got := shouldPrintCommandError(tc.cmd, root); got != tc.want {
+ t.Errorf("shouldPrintCommandError() = %v, want %v; a wrong answer here either prints the error twice or swallows it entirely", got, tc.want)
+ }
+ })
+ }
+}
diff --git a/cmd/pinchtab/cmd_cli_management.go b/cmd/pinchtab/cmd_cli_management.go
index dccd5c1b..d3fd1404 100644
--- a/cmd/pinchtab/cmd_cli_management.go
+++ b/cmd/pinchtab/cmd_cli_management.go
@@ -1,19 +1,39 @@
package main
import (
+ "fmt"
+
browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/urls"
"github.com/spf13/cobra"
)
+func listInstances(cmd *cobra.Command) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.Instances(rt.client, rt.base, rt.token, cmd)
+ })
+}
+
+var instanceListCmd = &cobra.Command{
+ Use: "list",
+ Short: "List browser instances",
+ Args: cobra.NoArgs,
+ Run: func(cmd *cobra.Command, args []string) {
+ listInstances(cmd)
+ },
+}
+
+// instancesCmd is the pre-`instance list` spelling. It stays runnable so
+// existing scripts keep working, and hidden so the root listing no longer
+// offers two commands one character apart for the same subject.
var instancesCmd = &cobra.Command{
- Use: "instances",
- Short: "List or manage instances",
+ Use: "instances",
+ Short: "List browser instances (deprecated: use \"pinchtab instance list\")",
+ Hidden: true,
+ Deprecated: "use \"pinchtab instance list\" instead.",
Run: func(cmd *cobra.Command, args []string) {
- runCLI(func(rt cliRuntime) {
- browseractions.Instances(rt.client, rt.base, rt.token, cmd)
- })
+ listInstances(cmd)
},
}
@@ -74,6 +94,26 @@ var instanceCmd = &cobra.Command{
Short: "Manage browser instances",
}
+// instanceIDArgs replaces cobra's "accepts 1 arg(s), received 0" on the
+// subcommands that need an instance id. The id only comes from one place, so
+// the error says where rather than leaving the operator to find it.
+func instanceIDArgs(count int) cobra.PositionalArgs {
+ return func(cmd *cobra.Command, args []string) error {
+ if len(args) == count {
+ return nil
+ }
+ return fmt.Errorf("%s needs %s; run \"pinchtab instance list\" to see running instances and their ids",
+ cmd.CommandPath(), pluralArgs(count))
+ }
+}
+
+func pluralArgs(count int) string {
+ if count == 1 {
+ return "an instance id"
+ }
+ return "an instance id and a URL"
+}
+
var startInstanceCmd = &cobra.Command{
Use: "start",
Short: "Start a browser instance",
@@ -87,7 +127,7 @@ var startInstanceCmd = &cobra.Command{
var instanceNavigateCmd = &cobra.Command{
Use: "navigate <id> <url>",
Short: "Navigate an instance to a URL",
- Args: cobra.ExactArgs(2),
+ Args: instanceIDArgs(2),
Run: func(cmd *cobra.Command, args []string) {
args[1] = urls.Normalize(args[1])
runCLI(func(rt cliRuntime) {
@@ -99,7 +139,7 @@ var instanceNavigateCmd = &cobra.Command{
var instanceStopCmd = &cobra.Command{
Use: "stop <id>",
Short: "Stop a browser instance",
- Args: cobra.ExactArgs(1),
+ Args: instanceIDArgs(1),
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.InstanceStop(rt.client, rt.base, rt.token, args)
@@ -110,7 +150,7 @@ var instanceStopCmd = &cobra.Command{
var instanceRestartCmd = &cobra.Command{
Use: "restart <id>",
Short: "Soft restart the browser process for an instance",
- Args: cobra.ExactArgs(1),
+ Args: instanceIDArgs(1),
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.InstanceRestart(rt.client, rt.base, rt.token, args)
@@ -121,7 +161,7 @@ var instanceRestartCmd = &cobra.Command{
var instanceLogsCmd = &cobra.Command{
Use: "logs <id>",
Short: "Get instance logs",
- Args: cobra.ExactArgs(1),
+ Args: instanceIDArgs(1),
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.InstanceLogs(rt.client, rt.base, rt.token, args)
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index f0cddb09..bb0d43a3 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -54,7 +54,7 @@ func registerBrowserCommands() {
func registerManagementCommands() {
setCommandGroup("management", instancesCmd, healthCmd, profilesCmd, activityCmd, instanceCmd)
- instanceCmd.AddCommand(startInstanceCmd, instanceNavigateCmd, instanceStopCmd, instanceRestartCmd, instanceLogsCmd)
+ instanceCmd.AddCommand(instanceListCmd, startInstanceCmd, instanceNavigateCmd, instanceStopCmd, instanceRestartCmd, instanceLogsCmd)
activityCmd.AddCommand(activityTabCmd)
profilesCmd.AddCommand(profilesPruneCmd)
diff --git a/cmd/pinchtab/root.go b/cmd/pinchtab/root.go
index fbb0eec1..8a824869 100644
--- a/cmd/pinchtab/root.go
+++ b/cmd/pinchtab/root.go
@@ -56,10 +56,24 @@ func Execute() {
safelog.InstallDefault()
installUnknownSubcommandGuard(rootCmd)
rootCmd.SetArgs(rewriteNegativeNumberArgs(rootCmd, os.Args[1:]))
- if err := rootCmd.Execute(); err != nil {
+ cmd, err := rootCmd.ExecuteC()
+ if err == nil {
+ return
+ }
+ if shouldPrintCommandError(cmd, rootCmd) {
fmt.Fprintln(os.Stderr, err)
- os.Exit(commandExitCode(err))
}
+ os.Exit(commandExitCode(err))
+}
+
+// shouldPrintCommandError reports whether Execute still owes the user an error
+// line. cobra prints the error itself unless the command or the root silenced
+// it, so printing unconditionally showed every failure twice.
+func shouldPrintCommandError(cmd, root *cobra.Command) bool {
+ if cmd == nil {
+ return true
+ }
+ return cmd.SilenceErrors || root.SilenceErrors
}
type commandExitError struct {
diff --git a/cmd/pinchtab/unknown_subcommand_test.go b/cmd/pinchtab/unknown_subcommand_test.go
index 78489709..3989d231 100644
--- a/cmd/pinchtab/unknown_subcommand_test.go
+++ b/cmd/pinchtab/unknown_subcommand_test.go
@@ -173,12 +173,17 @@ func TestExecuteInstallsTheGuard(t *testing.T) {
}
body := string(src)
install := strings.Index(body, "installUnknownSubcommandGuard(rootCmd)")
- execute := strings.Index(body, "rootCmd.Execute()")
+ // Prefix match: the call has been both Execute() and ExecuteC(), and a
+ // rename must not read as an ordering failure.
+ execute := strings.Index(body, "rootCmd.Execute")
if install < 0 {
t.Fatal("Execute no longer installs the unknown-subcommand guard, so every group is back to exit 0")
}
+ if execute < 0 {
+ t.Fatal("Execute no longer runs the command tree through rootCmd.Execute/ExecuteC; re-point this ordering guard at whatever runs it rather than deleting it")
+ }
if execute < install {
- t.Error("the guard is installed after rootCmd.Execute, which is too late to matter")
+ t.Error("the guard is installed after the command tree runs, which is too late to matter")
}
}
diff --git a/docs/commands.md b/docs/commands.md
index e2978ddd..86459222 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -319,7 +319,7 @@ pinchtab record status # Check recording status
## Instances, Profiles, And Activity
```bash
-pinchtab instances # List running instances
+pinchtab instance list # List running instances
pinchtab instance start # Start an instance
pinchtab instance start --profile <id-or-name>
pinchtab instance start --mode headed
diff --git a/docs/guides/attach-chrome.md b/docs/guides/attach-chrome.md
index cd3e13e7..c6c9aecd 100644
--- a/docs/guides/attach-chrome.md
+++ b/docs/guides/attach-chrome.md
@@ -176,7 +176,7 @@ Notes:
```bash
curl -s http://localhost:9867/instances | jq .
# CLI Alternative
-pinchtab instances
+pinchtab instance list
```
An attached instance appears in the normal instance list with:
diff --git a/docs/guides/cloakbrowser.md b/docs/guides/cloakbrowser.md
index e4f3001a..0583031d 100644
--- a/docs/guides/cloakbrowser.md
+++ b/docs/guides/cloakbrowser.md
@@ -242,7 +242,7 @@ Look for these fields:
If launch fails, inspect the instance:
```bash
-pinchtab instances
+pinchtab instance list
pinchtab instance logs <instance-id>
```
diff --git a/docs/reference/instances.md b/docs/reference/instances.md
index e9fc620f..08844cf4 100644
--- a/docs/reference/instances.md
+++ b/docs/reference/instances.md
@@ -17,13 +17,13 @@ curl http://localhost:9867/instances
# Response: JSON array (see below)
# CLI Alternative (human-readable by default)
-pinchtab instances
+pinchtab instance list
# Output: inst_0a89 9999 headed running
-pinchtab instances --json # Full JSON response
+pinchtab instance list --json # Full JSON response
```
-`pinchtab instances` is the simplest way to inspect the current fleet from the CLI.
+`pinchtab instance list` is the simplest way to inspect the current fleet from the CLI. The older `pinchtab instances` spelling still runs as a deprecated alias.
Response shape:
diff --git a/docs/showcase.md b/docs/showcase.md
index 70e7fd91..b4ad0c72 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -227,7 +227,7 @@ curl -s -X POST http://127.0.0.1:9867/instances/attach \
```bash
curl -s http://127.0.0.1:9867/instances | jq .
# CLI Alternative
-pinchtab instances
+pinchtab instance list
```
This is useful when:
diff --git a/internal/cli/styles.go b/internal/cli/styles.go
index 0b563618..072024ef 100644
--- a/internal/cli/styles.go
+++ b/internal/cli/styles.go
@@ -60,13 +60,13 @@ func SetupUsage(root *cobra.Command) {
{{.CommandPath}} server # Starts the full server
{{end}}
-%s:
+{{if .HasAvailableSubCommands}}%s:
{{range .Groups}}{{$group := .ID}}
{{.Title}}:
{{range $.Commands}}{{if eq .GroupID $group}}{{if not .Hidden}} %s {{.Short}}
{{end}}{{end}}{{end}}{{end}}{{range $.Commands}}{{if and (eq .GroupID "") .IsAvailableCommand}} %s {{.Short}}
{{end}}{{end}}
-{{if .HasAvailableLocalFlags}}
+{{end}}{{if .HasAvailableLocalFlags}}
%s:
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}
{{end}}
diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.json
index 2728a750..c9eadb1b 100644
--- a/internal/mcp/testdata/preamble_budget.json
+++ b/internal/mcp/testdata/preamble_budget.json
@@ -16,8 +16,8 @@
{
"surface": "skills/pinchtab/SKILL.md",
"minBytes": 10176,
- "maxBytes": 20352,
+ "maxBytes": 20356,
"takenOn": "2026-08-22",
- "commit": "9cb14d50"
+ "commit": "552ea6f9"
}
]
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index e2002da6..0a6b48ed 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -117,7 +117,7 @@ After changing config with the server running, restart to apply: `pinchtab serve
pinchtab server | health
pinchtab server stop # stop any running server (foreground or background)
pinchtab server restart # stop + restart in background (applies config changes)
-pinchtab instances | profiles
+pinchtab instance list | profiles
pinchtab --server http://localhost:9868 snap -i -c # target a specific instance
```
diff --git a/skills/pinchtab/references/agent-optimization.md b/skills/pinchtab/references/agent-optimization.md
index e6bc3d83..4d785098 100644
--- a/skills/pinchtab/references/agent-optimization.md
+++ b/skills/pinchtab/references/agent-optimization.md
@@ -142,7 +142,7 @@ pinchtab server # restart in the foreground, or use `pinchtab nav <url>
pinchtab health # confirm up before continuing
```
-For fleet workflows: check `pinchtab instances` to confirm the right instance is running.
+For fleet workflows: check `pinchtab instance list` to confirm the right instance is running.
---
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index 119b7187..c6ce096a 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -349,7 +349,7 @@ pinchtab profiles
pinchtab instance start --profile work
```
-### `pinchtab instances`
+### `pinchtab instance list`
List running PinchTab instances across profiles.
---
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 9c83bd9c..6da84899 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -142,7 +142,7 @@ The MCP surface is intentionally scoped to browser automation. The following are
| CAPTCHA or human verification | ❌ Not available | Hand the step to the user |
| Modify stealth or fingerprint settings | ❌ Not available | Not part of an agent workflow |
| Start or stop the PinchTab server | ❌ Not available | Use `pinchtab server` or `pinchtab daemon` CLI |
-| Manage fleet instances | ❌ Not available | Use `pinchtab instances` CLI |
+| Manage fleet instances | ❌ Not available | Use `pinchtab instance list` CLI |
| Read/write PinchTab config | ❌ Not available | Edit `~/.pinchtab/config.json` directly |
For supported non-MCP browser work, use the CLI commands alongside the MCP tools. Keep privileged controls within the explicit authorization and data-handling rules above.
diff --git a/tests/optimization-setup/group-00.md b/tests/optimization-setup/group-00.md
index f6191d59..8fd400c9 100644
--- a/tests/optimization-setup/group-00.md
+++ b/tests/optimization-setup/group-00.md
@@ -17,7 +17,7 @@ Run a single navigation against the fixture server with no preceding `pinchtab`
- The command exits 0 and prints a tab ID. Capture it (`TAB_ID=...`) and reuse for every step in group 1.
- `$PINCHTAB_CONFIG` now exists on disk — auto-created by the CLI.
- A `pinchtab server` process is running on default port `9867` (`lsof -i :9867` or check `ps`).
-- A managed Chrome instance has come up (`./pinchtab instances` shows at least one row, `status=running`).
+- A managed Chrome instance has come up (`./pinchtab instance list` shows at least one row, `status=running`).
### 0.2 Auto-created config matches OOTB defaults
Without ever running `config init` manually, inspect what the auto-flow wrote: