go-cobra-flag-registration

Answer

Root cause: cobra.Command.Commands() returns subcommands sorted alphabetically by name, not in the order you called AddCommand. So cmd.Commands()[1] is the second subcommand alphabetically — and cmd.Commands()[1].Flags().String(...) registers the flag on whatever command happens to sit at that index. If subcommand names ever change, get reordered, or a new one is added, flags silently migrate to a different command.

The fix: keep a variable reference to the subcommand at creation time and register flags on that reference. Never index cmd.Commands().

package main

import "github.com/spf13/cobra"

// BAD — breaks the moment subcommand order/names change:
func badRoot() *cobra.Command {
    root := &cobra.Command{Use: "app"}
    root.AddCommand(&cobra.Command{Use: "zebra", Run: func(c *cobra.Command, a []string) {}})
    root.AddCommand(&cobra.Command{Use: "apple", Run: func(c *cobra.Command, a []string) {}})

    // Compiles, but lands on "zebra" (alphabetically 2nd), NOT "apple" (2nd defined)
    root.Commands()[1].Flags().String("bug-flag", "", "mislocated")
    return root
}

// GOOD — variable reference + explicit AddCommand:
func goodRoot() *cobra.Command {
    root := &cobra.Command{Use: "app"}

    createCmd := &cobra.Command{Use: "create", Run: func(c *cobra.Command, a []string) {}}
    root.AddCommand(createCmd) // register first, then wire flags
    createCmd.Flags().String("name", "", "the file name")

    // safe even though more commands get added later
    root.AddCommand(&cobra.Command{Use: "zebra", Run: func(c *cobra.Command, a []string) {}})
    return root
}

Key points: - Declare the *cobra.Command variable, AddCommand it, then call .Flags() on the variable — order of those three lines is irrelevant to correctness. - The same trap applies to cmd.Commands() for help text, aliases, or any per-subcommand wiring: resolve subcommands by Find([]string{...}) or by variable reference, never by positional index.