Developing Cli Apps

Adding a New Command

1. Create a new file in cmd/ (camelCase name matching the command)
2. Define a cobra.Command variable with Use and Short fields
3. In init(): register with rootCmd.AddCommand(), define flags, bind to Viper
4. Suppress the init lint: //nolint:gochecknoinits // Cobra requires an init function to set up the command structure.

Flag Conventions

• Use StringVar/BoolVar/CountVarP (pointer-binding) for all flags
• Bind every flag to Viper: viper.BindPFlag("name", cmd.Flags().Lookup("name"))
• Use kebab-case for flag names: --git-clone-protocol, not --gitCloneProtocol
• Provide meaningful defaults and descriptions

Initialization Chain

Global dependencies are initialized via cobra.OnInitialize() in root.go. Each initializer sets a package-level global. Order matters — later initializers may depend on earlier ones. Read root.go for the current chain.

Error Handling in Commands

• Use RunE (not Run) — return errors from the function; Cobra handles display and exit
• Set SilenceUsage: true on the root command so runtime errors don't print usage
• Keep RunE functions thin — delegate to business logic packages

Signal Handling and Cleanup

• Register signal handlers (e.g., os.Interrupt, syscall.SIGTERM) early in the root command initialization
• Use PersistentPostRun on the root command for successful completion cleanup
• Provide a dedicated cleanup function for error and signal exit paths
• Always clean up resources (loggers, temp files) on all exit paths

Key Rules

• Commands should not import each other; share state via package-level variables in cmd/
• Use fmt.Fprint(os.Stderr, ...) for error output