cmd/tailscale/cli: prefix all --help usages with "tailscale ...", som…

…e tidying

Also capitalises the start of all ShortHelp, allows subcommands to be hidden
with a "HIDDEN: " prefix in their ShortHelp, and adds a TS_DUMP_HELP envknob
to look at all --help messages together.

Fixes #11664

Signed-off-by: Paul Scott <paul@tailscale.com>

cmd/tailscale/cli/bugreport.go

@@ -17,7 +17,7 @@ var bugReportCmd = &ffcli.Command{
 	Name:       "bugreport",
 	Exec:       runBugReport,
 	ShortHelp:  "Print a shareable identifier to help diagnose issues",
-	ShortUsage: "bugreport [note]",
+	ShortUsage: "tailscale bugreport [note]",
 	FlagSet: (func() *flag.FlagSet {
 		fs := newFlagSet("bugreport")
 		fs.BoolVar(&bugReportArgs.diagnose, "diagnose", false, "run additional in-depth checks")

cmd/tailscale/cli/cert.go

@@ -28,7 +28,7 @@ var certCmd = &ffcli.Command{
 	Name:       "cert",
 	Exec:       runCert,
 	ShortHelp:  "Get TLS certs",
-	ShortUsage: "cert [flags] <domain>",
+	ShortUsage: "tailscale cert [flags] <domain>",
 	FlagSet: (func() *flag.FlagSet {
 		fs := newFlagSet("cert")
 		fs.StringVar(&certArgs.certFile, "cert-file", "", "output cert file or \"-\" for stdout; defaults to DOMAIN.crt if --cert-file and --key-file are both unset")

cmd/tailscale/cli/cli.go

@@ -14,7 +14,6 @@ import (
 	"log"
 	"os"
 	"runtime"
-	"slices"
 	"strings"
 	"sync"
 	"text/tabwriter"
@@ -95,6 +94,49 @@ func Run(args []string) (err error) {
 		})
 	})
 
+	rootCmd := newRootCmd()
+	if err := rootCmd.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+
+	if envknob.Bool("TS_DUMP_HELP") {
+		walkCommands(rootCmd, func(c *ffcli.Command) {
+			fmt.Println("===")
+			// UsageFuncs are typically called during Command.Run which ensures
+			// FlagSet is not nil.
+			if c.FlagSet == nil {
+				c.FlagSet = flag.NewFlagSet(c.Name, flag.ContinueOnError)
+			}
+			if c.UsageFunc != nil {
+				fmt.Println(c.UsageFunc(c))
+			} else {
+				fmt.Println(ffcli.DefaultUsageFunc(c))
+			}
+		})
+		return
+	}
+
+	localClient.Socket = rootArgs.socket
+	rootCmd.FlagSet.Visit(func(f *flag.Flag) {
+		if f.Name == "socket" {
+			localClient.UseSocketOnly = true
+		}
+	})
+
+	err = rootCmd.Run(context.Background())
+	if tailscale.IsAccessDeniedError(err) && os.Getuid() != 0 && runtime.GOOS != "windows" {
+		return fmt.Errorf("%v\n\nUse 'sudo tailscale %s' or 'tailscale up --operator=$USER' to not require root.", err, strings.Join(args, " "))
+	}
+	if errors.Is(err, flag.ErrHelp) {
+		return nil
+	}
+	return err
+}
+
+func newRootCmd() *ffcli.Command {
 	rootfs := newFlagSet("tailscale")
 	rootfs.StringVar(&rootArgs.socket, "socket", paths.DefaultTailscaledSocket(), "path to tailscaled socket")
 
@@ -134,56 +176,28 @@ change in the future.
 			exitNodeCmd(),
 			updateCmd,
 			whoisCmd,
+			debugCmd,
+			driveCmd,
 		},
-		FlagSet:   rootfs,
-		Exec:      func(context.Context, []string) error { return flag.ErrHelp },
-		UsageFunc: usageFunc,
+		FlagSet: rootfs,
+		Exec:    func(context.Context, []string) error { return flag.ErrHelp },
 	}
 	if envknob.UseWIPCode() {
 		rootCmd.Subcommands = append(rootCmd.Subcommands,
 			idTokenCmd,
 		)
 	}
 
-	// Don't advertise these commands, but they're still explicitly available.
-	switch {
-	case slices.Contains(args, "debug"):
-		rootCmd.Subcommands = append(rootCmd.Subcommands, debugCmd)
-	case slices.Contains(args, "drive"):
-		rootCmd.Subcommands = append(rootCmd.Subcommands, driveCmd)
-	}
 	if runtime.GOOS == "linux" && distro.Get() == distro.Synology {
 		rootCmd.Subcommands = append(rootCmd.Subcommands, configureHostCmd)
 	}
 
-	for _, c := range rootCmd.Subcommands {
+	walkCommands(rootCmd, func(c *ffcli.Command) {
 		if c.UsageFunc == nil {
 			c.UsageFunc = usageFunc
 		}
-	}
-
-	if err := rootCmd.Parse(args); err != nil {
-		if errors.Is(err, flag.ErrHelp) {
-			return nil
-		}
-		return err
-	}
-
-	localClient.Socket = rootArgs.socket
-	rootfs.Visit(func(f *flag.Flag) {
-		if f.Name == "socket" {
-			localClient.UseSocketOnly = true
-		}
 	})
-
-	err = rootCmd.Run(context.Background())
-	if tailscale.IsAccessDeniedError(err) && os.Getuid() != 0 && runtime.GOOS != "windows" {
-		return fmt.Errorf("%v\n\nUse 'sudo tailscale %s' or 'tailscale up --operator=$USER' to not require root.", err, strings.Join(args, " "))
-	}
-	if errors.Is(err, flag.ErrHelp) {
-		return nil
-	}
-	return err
+	return rootCmd
 }
 
 func fatalf(format string, a ...any) {
@@ -202,6 +216,13 @@ var rootArgs struct {
 	socket string
 }
 
+func walkCommands(cmd *ffcli.Command, f func(*ffcli.Command)) {
+	f(cmd)
+	for _, sub := range cmd.Subcommands {
+		walkCommands(sub, f)
+	}
+}
+
 // usageFuncNoDefaultValues is like usageFunc but doesn't print default values.
 func usageFuncNoDefaultValues(c *ffcli.Command) string {
 	return usageFuncOpt(c, false)
@@ -213,23 +234,32 @@ func usageFunc(c *ffcli.Command) string {
 
 func usageFuncOpt(c *ffcli.Command, withDefaults bool) string {
 	var b strings.Builder
+	const hiddenPrefix = "HIDDEN: "
+
+	if c.ShortHelp != "" {
+		fmt.Fprintf(&b, "%s\n\n", c.ShortHelp)
+	}
 
 	fmt.Fprintf(&b, "USAGE\n")
 	if c.ShortUsage != "" {
-		fmt.Fprintf(&b, "  %s\n", c.ShortUsage)
+		fmt.Fprintf(&b, "  %s\n", strings.ReplaceAll(c.ShortUsage, "\n", "\n  "))
 	} else {
 		fmt.Fprintf(&b, "  %s\n", c.Name)
 	}
 	fmt.Fprintf(&b, "\n")
 
 	if c.LongHelp != "" {
-		fmt.Fprintf(&b, "%s\n\n", c.LongHelp)
+		help, _ := strings.CutPrefix(c.LongHelp, hiddenPrefix)
+		fmt.Fprintf(&b, "%s\n\n", help)
 	}
 
 	if len(c.Subcommands) > 0 {
 		fmt.Fprintf(&b, "SUBCOMMANDS\n")
 		tw := tabwriter.NewWriter(&b, 0, 2, 2, ' ', 0)
 		for _, subcommand := range c.Subcommands {
+			if strings.HasPrefix(subcommand.LongHelp, hiddenPrefix) {
+				continue
+			}
 			fmt.Fprintf(tw, "  %s\t%s\n", subcommand.Name, subcommand.ShortHelp)
 		}
 		tw.Flush()
@@ -242,7 +272,7 @@ func usageFuncOpt(c *ffcli.Command, withDefaults bool) string {
 		c.FlagSet.VisitAll(func(f *flag.Flag) {
 			var s string
 			name, usage := flag.UnquoteUsage(f)
-			if strings.HasPrefix(usage, "HIDDEN: ") {
+			if strings.HasPrefix(usage, hiddenPrefix) {
 				return
 			}
 			if isBoolFlag(f) {

cmd/tailscale/cli/cli_test.go

@@ -16,6 +16,7 @@ import (
 
 	qt "github.com/frankban/quicktest"
 	"github.com/google/go-cmp/cmp"
+	"github.com/peterbourgon/ff/v3/ffcli"
 	"tailscale.com/envknob"
 	"tailscale.com/health/healthmsg"
 	"tailscale.com/ipn"
@@ -29,15 +30,37 @@ import (
 	"tailscale.com/version/distro"
 )
 
+func TestPanicIfAnyEnvCheckedInInit(t *testing.T) {
+	envknob.PanicIfAnyEnvCheckedInInit()
+}
+
+func TestShortUsage_FullCmd(t *testing.T) {
+	t.Setenv("TAILSCALE_USE_WIP_CODE", "1")
+	if !envknob.UseWIPCode() {
+		t.Fatal("expected envknob.UseWIPCode() to be true")
+	}
+
+	// Some commands have more than one path from the root, so investigate all
+	// paths before we report errors.
+	ok := make(map[*ffcli.Command]bool)
+	root := newRootCmd()
+	walkCommands(root, func(c *ffcli.Command) {
+		if !ok[c] {
+			ok[c] = strings.HasPrefix(c.ShortUsage, "tailscale ") && (c.Name == "tailscale" || strings.Contains(c.ShortUsage, " "+c.Name+" ") || strings.HasSuffix(c.ShortUsage, " "+c.Name))
+		}
+	})
+	walkCommands(root, func(c *ffcli.Command) {
+		if !ok[c] {
+			t.Errorf("subcommand %s should show full usage ('tailscale ... %s ...') in ShortUsage (%q)", c.Name, c.Name, c.ShortUsage)
+		}
+	})
+}
+
 // geese is a collection of gooses. It need not be complete.
 // But it should include anything handled specially (e.g. linux, windows)
 // and at least one thing that's not (darwin, freebsd).
 var geese = []string{"linux", "darwin", "windows", "freebsd"}
 
-func TestPanicIfAnyEnvCheckedInInit(t *testing.T) {
-	envknob.PanicIfAnyEnvCheckedInInit()
-}
-
 // Test that checkForAccidentalSettingReverts's updateMaskedPrefsFromUpFlag can handle
 // all flags. This will panic if a new flag creeps in that's unhandled.
 //

cmd/tailscale/cli/configure-kube.go

@@ -27,7 +27,7 @@ func init() {
 var configureKubeconfigCmd = &ffcli.Command{
 	Name:       "kubeconfig",
 	ShortHelp:  "[ALPHA] Connect to a Kubernetes cluster using a Tailscale Auth Proxy",
-	ShortUsage: "kubeconfig <hostname-or-fqdn>",
+	ShortUsage: "tailscale configure kubeconfig <hostname-or-fqdn>",
 	LongHelp: strings.TrimSpace(`
 Run this command to configure kubectl to connect to a Kubernetes cluster over Tailscale.
 

cmd/tailscale/cli/configure-synology.go

@@ -22,20 +22,22 @@ import (
 // used to configure Synology devices, but is now a compatibility alias to
 // "tailscale configure synology".
 var configureHostCmd = &ffcli.Command{
-	Name:      "configure-host",
-	Exec:      runConfigureSynology,
-	ShortHelp: synologyConfigureCmd.ShortHelp,
-	LongHelp:  synologyConfigureCmd.LongHelp,
+	Name:       "configure-host",
+	Exec:       runConfigureSynology,
+	ShortUsage: "tailscale configure-host",
+	ShortHelp:  synologyConfigureCmd.ShortHelp,
+	LongHelp:   synologyConfigureCmd.LongHelp,
 	FlagSet: (func() *flag.FlagSet {
 		fs := newFlagSet("configure-host")
 		return fs
 	})(),
 }
 
 var synologyConfigureCmd = &ffcli.Command{
-	Name:      "synology",
-	Exec:      runConfigureSynology,
-	ShortHelp: "Configure Synology to enable outbound connections",
+	Name:       "synology",
+	Exec:       runConfigureSynology,
+	ShortUsage: "tailscale configure synology",
+	ShortHelp:  "Configure Synology to enable outbound connections",
 	LongHelp: strings.TrimSpace(`
 This command is intended to run at boot as root on a Synology device to
 create the /dev/net/tun device and give the tailscaled binary permission

cmd/tailscale/cli/configure.go

@@ -14,8 +14,9 @@ import (
 )
 
 var configureCmd = &ffcli.Command{
-	Name:      "configure",
-	ShortHelp: "[ALPHA] Configure the host to enable more Tailscale features",
+	Name:       "configure",
+	ShortUsage: "tailscale configure <subcommand>",
+	ShortHelp:  "[ALPHA] Configure the host to enable more Tailscale features",
 	LongHelp: strings.TrimSpace(`
 The 'configure' set of commands are intended to provide a way to enable different
 services on the host to use Tailscale in more ways.