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.gonew file mode 100644index 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.goindex dccd5c1b..d3fd1404 100644--- a/cmd/pinchtab/cmd_cli_management.go+++ b/cmd/pinchtab/cmd_cli_management.go@@ -1,19 +1,39 @@package mainimport (+ "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.goindex 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.goindex 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.goindex 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.mdindex 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 instancespinchtab instance start # Start an instancepinchtab instance start --profile <id-or-name>pinchtab instance start --mode headeddiff --git a/docs/guides/attach-chrome.md b/docs/guides/attach-chrome.mdindex cd3e13e7..c6c9aecd 100644--- a/docs/guides/attach-chrome.md+++ b/docs/guides/attach-chrome.md@@ -176,7 +176,7 @@ Notes:```bashcurl -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.mdindex 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 listpinchtab instance logs <instance-id>```diff --git a/docs/reference/instances.md b/docs/reference/instances.mdindex 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.mdindex 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 \```bashcurl -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.goindex 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.jsonindex 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.mdindex 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 servepinchtab server | healthpinchtab 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 | profilespinchtab --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.mdindex 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.mdindex 119b7187..c6ce096a 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -349,7 +349,7 @@ pinchtab profilespinchtab 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.mdindex 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.mdindex 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 defaultsWithout ever running `config init` manually, inspect what the auto-flow wrote: