fix: collapse the usage string to a single line

cobra's default advertised two usage modes for a runnable command with
subcommands — "flagsmith [flags]" and "flagsmith [command]" — which reads
oddly for a root whose bare run just prints help. Rewrite the Usage block
so each command shows one context-appropriate line: "<path> [command]
[flags]" for groups, or the command's own use line for leaves. Done as a
string replace on cobra's own default template so it survives version
bumps (no-op if the block changes, guarded by a test).

beep boop

Author: khvn26

internal/cmd/cmd_test.go

@@ -2423,6 +2423,31 @@ func TestFlagDelete(t *testing.T) {
 	})
 }
 
+func TestUsageIsSingleLine(t *testing.T) {
+	// Given / When — root help
+	out, err := run("", "--help")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Then — one context-appropriate line, not cobra's default two-line form
+	if !strings.Contains(out, "flagsmith [command] [flags]") {
+		t.Errorf("root usage = %q, want the single-line form", out)
+	}
+	if strings.Contains(out, "flagsmith [flags]\n") {
+		t.Errorf("root usage still shows the two-line form:\n%s", out)
+	}
+
+	// Leaf commands render their own use line
+	leaf, err := run("", "flag", "list", "--help")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(leaf, "flagsmith flag list [flags]") {
+		t.Errorf("leaf usage = %q, want its own use line", leaf)
+	}
+}
+
 func TestFlagIdentity(t *testing.T) {
 	// max_items is feature id 2 in defaultFeatures; user-1 is core identity 501.
 

internal/cmd/root.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -12,6 +13,18 @@ import (
 	"github.com/Flagsmith/flagsmith-cli/internal/output"
 )
 
+// singleLineUsage rewrites cobra's default two-line Usage block (one line for
+// running the command bare, another for a subcommand) into a single
+// context-appropriate line: "<path> [command] [flags]" for groups, or the
+// command's own use line for leaves. Applied as a string replace on cobra's
+// own template so it survives version bumps (a no-op if the block ever changes,
+// caught by TestUsageIsSingleLine).
+func singleLineUsage(template string) string {
+	const defaultBlock = "Usage:{{if .Runnable}}\n  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}\n  {{.CommandPath}} [command]{{end}}"
+	const oneLine = "Usage:{{if .HasAvailableSubCommands}}\n  {{.CommandPath}} [command] [flags]{{else}}\n  {{.UseLine}}{{end}}"
+	return strings.Replace(template, defaultBlock, oneLine, 1)
+}
+
 // apiURL is the resolved instance URL for the current invocation, set by
 // applyContext. Flag values live in the *Flag variables below.
 var apiURL string
@@ -116,6 +129,8 @@ func init() {
 	flags.StringVar(&jqFlag, "jq", "",
 		"filter JSON output through a jq expression (implies --json)")
 
+	rootCmd.SetUsageTemplate(singleLineUsage(rootCmd.UsageTemplate()))
+
 	// Hidden aliases: --api for --api-url, --no-input for --yes.
 	rootCmd.SetGlobalNormalizationFunc(func(f *pflag.FlagSet, name string) pflag.NormalizedName {
 		switch name {