Default to running the default agent when no subcommand is given

When invoked without a subcommand (e.g. bare "cagent" or "cagent --debug"),
automatically prepend "run" so the default agent is launched. Users can
still use "cagent --help" to list available commands.

Assisted-By: cagent

Author: dgageot

cmd/root/root.go

@@ -147,6 +147,11 @@ We collect anonymous usage data to help improve cagent. To disable:
 	}
 
 	rootCmd := NewRootCmd()
+
+	// When no subcommand is given, default to "run" (which runs the default agent).
+	// Users can use "cagent --help" to see available commands.
+	args = defaultToRun(rootCmd, args)
+
 	rootCmd.SetArgs(args)
 	rootCmd.SetIn(stdin)
 	rootCmd.SetOut(stdout)
@@ -182,6 +187,42 @@ We collect anonymous usage data to help improve cagent. To disable:
 	return nil
 }
 
+// defaultToRun prepends "run" to the argument list when no subcommand is
+// specified so that bare "cagent" (or "cagent --debug", etc.) launches the
+// default agent. Help flags (--help / -h) are left alone.
+func defaultToRun(rootCmd *cobra.Command, args []string) []string {
+	for _, arg := range args {
+		switch {
+		case arg == "--":
+			// End of flags – no subcommand found.
+			return append([]string{"run"}, args...)
+		case arg == "--help" || arg == "-h":
+			return args
+		case strings.HasPrefix(arg, "-"):
+			continue
+		case isSubcommand(rootCmd, arg):
+			return args
+		default:
+			return append([]string{"run"}, args...)
+		}
+	}
+
+	return append([]string{"run"}, args...)
+}
+
+// isSubcommand reports whether name matches a registered subcommand or alias.
+func isSubcommand(cmd *cobra.Command, name string) bool {
+	if name == "help" {
+		return true
+	}
+	for _, sub := range cmd.Commands() {
+		if sub.Name() == name || sub.HasAlias(name) {
+			return true
+		}
+	}
+	return false
+}
+
 func processErr(ctx context.Context, err error, stderr io.Writer, rootCmd *cobra.Command) error {
 	if ctx.Err() != nil {
 		return ctx.Err()

cmd/root/root_test.go

@@ -0,0 +1,99 @@
+package root
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDefaultToRun(t *testing.T) {
+	t.Parallel()
+
+	rootCmd := NewRootCmd()
+
+	tests := []struct {
+		name string
+		args []string
+		want []string
+	}{
+		{
+			name: "no args defaults to run",
+			args: []string{},
+			want: []string{"run"},
+		},
+		{
+			name: "nil args defaults to run",
+			args: nil,
+			want: []string{"run"},
+		},
+		{
+			name: "known subcommand kept as-is",
+			args: []string{"version"},
+			want: []string{"version"},
+		},
+		{
+			name: "run subcommand kept as-is",
+			args: []string{"run", "./agent.yaml"},
+			want: []string{"run", "./agent.yaml"},
+		},
+		{
+			name: "help subcommand kept as-is",
+			args: []string{"help"},
+			want: []string{"help"},
+		},
+		{
+			name: "--help flag kept as-is",
+			args: []string{"--help"},
+			want: []string{"--help"},
+		},
+		{
+			name: "-h flag kept as-is",
+			args: []string{"-h"},
+			want: []string{"-h"},
+		},
+		{
+			name: "only flags defaults to run",
+			args: []string{"--debug"},
+			want: []string{"run", "--debug"},
+		},
+		{
+			name: "flags with agent file defaults to run",
+			args: []string{"--debug", "./agent.yaml"},
+			want: []string{"run", "--debug", "./agent.yaml"},
+		},
+		{
+			name: "agent file without subcommand defaults to run",
+			args: []string{"./agent.yaml"},
+			want: []string{"run", "./agent.yaml"},
+		},
+		{
+			name: "new subcommand kept as-is",
+			args: []string{"new"},
+			want: []string{"new"},
+		},
+		{
+			name: "serve subcommand kept as-is",
+			args: []string{"serve", "mcp", "./agent.yaml"},
+			want: []string{"serve", "mcp", "./agent.yaml"},
+		},
+		{
+			name: "debug and help still shows help",
+			args: []string{"--debug", "--help"},
+			want: []string{"--debug", "--help"},
+		},
+		{
+			name: "agent file with flags defaults to run",
+			args: []string{"./agent.yaml", "--yolo"},
+			want: []string{"run", "./agent.yaml", "--yolo"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := defaultToRun(rootCmd, tt.args)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}