Error on bare group commands with explicit flags

internal/cli/help.go

@@ -17,6 +17,13 @@ import (
 // and a consistent styled layout for every subcommand.
 func rootHelpFunc() func(*cobra.Command, []string) {
 	return func(cmd *cobra.Command, args []string) {
+		// Bare group with explicit flags (e.g. "cards --in X"): suppress
+		// help output so Execute() can emit a usage error with non-zero exit.
+		// Must run before machine-help branches to avoid mixed output.
+		if isBareGroupWithFlags(cmd) {
+			return
+		}
+
 		pf := cmd.Root().PersistentFlags()
 		if agent, _ := pf.GetBool("agent"); agent {
 			emitAgentHelp(cmd)
@@ -30,10 +37,36 @@ func rootHelpFunc() func(*cobra.Command, []string) {
 			renderRootHelp(cmd.OutOrStdout(), cmd)
 			return
 		}
+
 		renderCommandHelp(cmd)
 	}
 }
 
+// hasExplicitLocalFlags reports whether any flag declared directly on cmd
+// (not inherited from parents) was explicitly set, excluding --help.
+func hasExplicitLocalFlags(cmd *cobra.Command) bool {
+	found := false
+	cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Changed && f.Name != "help" {
+			found = true
+		}
+	})
+	return found
+}
+
+// isBareGroupWithFlags reports whether cmd is a non-runnable group command
+// that was invoked bare (no subcommand) with explicitly-set local flags.
+// Explicit --help always renders help regardless of other flags.
+func isBareGroupWithFlags(cmd *cobra.Command) bool {
+	if cmd.Runnable() || !cmd.HasSubCommands() {
+		return false
+	}
+	if helpFlag := cmd.Flags().Lookup("help"); helpFlag != nil && helpFlag.Changed {
+		return false
+	}
+	return hasExplicitLocalFlags(cmd)
+}
+
 // curatedCategories defines the subset of categories and commands shown in root help.
 // Commands not listed here are discoverable via `basecamp commands`.
 var curatedCategories = []struct {

internal/cli/help_test.go

@@ -561,6 +561,73 @@ func TestRootHelpContainsJQFlag(t *testing.T) {
 	assert.Contains(t, out, "Filter JSON with jq expression")
 }
 
+func TestBareGroupWithFlagsSuppressesHelp(t *testing.T) {
+	// Bare group invocation with explicit local flags suppresses help output
+	// so cli.Execute() can emit a usage error. Cobra still returns nil —
+	// the error conversion happens in Execute() which calls os.Exit.
+	isolateHelpTest(t)
+
+	tests := []struct {
+		name   string
+		args   []string
+		addCmd func() *cobra.Command
+	}{
+		{"cards --in", []string{"cards", "--in", "myproject"}, commands.NewCardsCmd},
+		{"cards --project", []string{"cards", "--project", "myproject"}, commands.NewCardsCmd},
+		{"cards --in --json", []string{"cards", "--in", "myproject", "--json"}, commands.NewCardsCmd},
+		{"cards --in --agent", []string{"cards", "--in", "myproject", "--agent"}, commands.NewCardsCmd},
+		{"messages --in", []string{"messages", "--in", "myproject"}, commands.NewMessagesCmd},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			cmd := NewRootCmd()
+			cmd.AddCommand(tt.addCmd())
+			cmd.SetOut(&buf)
+			cmd.SetArgs(tt.args)
+
+			executedCmd, err := cmd.ExecuteC()
+			require.NoError(t, err, "Cobra returns nil for non-runnable commands")
+			assert.Empty(t, buf.String(), "help text should be suppressed")
+			assert.True(t, isBareGroupWithFlags(executedCmd),
+				"Execute() should detect this and convert to a usage error")
+		})
+	}
+}
+
+func TestBareGroupWithoutFlagsShowsHelp(t *testing.T) {
+	isolateHelpTest(t)
+
+	var buf bytes.Buffer
+	cmd := NewRootCmd()
+	cmd.AddCommand(commands.NewCardsCmd())
+	cmd.SetOut(&buf)
+	cmd.SetArgs([]string{"cards"})
+	err := cmd.Execute()
+
+	require.NoError(t, err)
+	out := buf.String()
+	assert.Contains(t, out, "COMMANDS")
+	assert.Contains(t, out, "USAGE")
+}
+
+func TestBareGroupWithFlagsAndHelpShowsHelp(t *testing.T) {
+	isolateHelpTest(t)
+
+	var buf bytes.Buffer
+	cmd := NewRootCmd()
+	cmd.AddCommand(commands.NewCardsCmd())
+	cmd.SetOut(&buf)
+	cmd.SetArgs([]string{"cards", "--in", "myproject", "--help"})
+	err := cmd.Execute()
+
+	require.NoError(t, err)
+	out := buf.String()
+	assert.Contains(t, out, "COMMANDS")
+	assert.Contains(t, out, "USAGE")
+}
+
 func TestGroupCommandHelpOmitsArguments(t *testing.T) {
 	isolateHelpTest(t)
 

internal/cli/root.go

@@ -295,6 +295,16 @@ func Execute() {
 
 	// Use ExecuteC to get the executed command (for correct context access)
 	executedCmd, err := cmd.ExecuteC()
+
+	// Bare group command with explicit flags (e.g. "cards --in X"): the help
+	// function suppressed output. Convert to a usage error.
+	if err == nil && executedCmd != cmd && isBareGroupWithFlags(executedCmd) {
+		err = output.ErrUsageHint(
+			"subcommand required",
+			"Usage: "+executedCmd.CommandPath()+" <command> [flags]",
+		)
+	}
+
 	if err != nil {
 		// When a command receives zero args but requires some, show help instead of an error —
 		// but only for interactive human users. Machine consumers (--agent, --json, piped stdout)