cobraFlagPrompt

README

Cobra Flag Prompt

Cobra Flag Prompt prompts users to enter values for required flags. It is an extension of Cobra, and requires that you use Cobra to set up the CLI for your program.

GoDoc

User Experience Before Cobra Flag Prompt

Without Cobra Flag Prompt, the program immediately terminates if the user did not enter a required flag and prints out which flag(s) were missing and all usage text for all flags. The user must then retype the command, add the new flag(s), identify the flag(s) usage text, and choose the correct value for the required flag. This isn't a big deal with programs which only have two options, but for programs with dozens of options the process becomes tedious.

Video: https://youtu.be/EhVW5Vl9KAE

User Experience After Cobra Flag Prompt

With Cobra Flag Prompt, the user is prompted for any missing required flags. To assist the user, the Usage information for the missing flag(s) is displayed when the user needs it.

Video: https://youtu.be/5sNhdYA5hc4

Usage

Usage is trivial. Replace calls to MarkFlagRequired with cobraFlagPrompt.MarkFlagRequired and calls to MarkPersistentFlagRequired with cobraFlagPrompt.MarkPersistentFlagRequired.

Advanced usage can be ascertained by reading the GoDoc or the source code.

Usage Walkthrough

First, get the package

go get github.com/Polyapp-LLC/cobraFlagPrompt

Then modify your existing code. Here is an example Cobra init() function for a program with 2 flags and which does NOT use cobraFlagPrompt:

func init() {
    rootCmd.Flags().StringVar(&EnvironmentName, "environmentName", "", `environment names can only be lowercase ascii characters and hyphens. Example: test-one`)
    rootCmd.PersistentFlags().StringVarP(&CloudName, "cloudName", "n", "", `cloud name must be one of the following strings: "AWS", "Azure", "Google", "localhost"`)
    
    err := rootCmd.MarkFlagRequired("environmentName")
    if err != nil {
        panic("rootCmd.MarkFlagRequired(environmentName): " + err.Error())
    }
    err = rootCmd.MarkPersistentFlagRequired("cloudName")
    if err != nil {
    	panic("rootCmd.MarkPersistentFlagRequired(cloudName): " + err.Error())
    }
}

Here is the same code, except it is using cobraFlagPrompt. Notice: rootCmd.MarkFlagRequired has been updated to: cobraFlagPrompt.MarkFlagRequired.

func init() {
    rootCmd.Flags().StringVar(&EnvironmentName, "environmentName", "", `environment names can only be lowercase ascii characters and hyphens. Example: test-one`)
    rootCmd.PersistentFlags().StringVarP(&CloudName, "cloudName", "n", "", `cloud name must be one of the following strings: "AWS", "Azure", "Google", "localhost"`)
    
    err := cobraFlagPrompt.MarkFlagRequired(rootCmd, "environmentName")
    if err != nil {
        panic("cobraFlagPrompt.MarkFlagRequired(environmentName): " + err.Error())
    }
    err = cobraFlagPrompt.MarkPersistentFlagRequired(rootCmd, "cloudName")
    if err != nil {
    	panic("cobraFlagPrompt.MarkPersistentFlagRequired(cloudName): " + err.Error())
    }
}

The results can be seen above (this is the code used in the example videos).

Support and Issues

Cobra Flag Prompt ought to work with all flag types supported by Cobra. Tests are in cobraFlagPrompt_test.go. Questions? Leave an Issue! Thanks :)

Documentation

Index

• func CobraFlagPromptPreRunE(cmd *cobra.Command, args []string, stdIn io.Reader, stdOut io.Writer) error
• func MarkFlagRequired(cmd *cobra.Command, name string) error
• func MarkPersistentFlagRequired(cmd *cobra.Command, name string) error
• func PromptForFlag(flag *pflag.Flag, stdIn io.Reader, stdOut io.Writer) error

Functions

func CobraFlagPromptPreRunE

func CobraFlagPromptPreRunE(cmd *cobra.Command, args []string, stdIn io.Reader, stdOut io.Writer) error

CobraFlagPromptPreRunE is the cobraFlagPrompt PreRunE code which will prompt the user to enter information for missing flags. cobraFlagPrompt makes an effort to call this function for you. Most developers will not need to call it manually. However, if you do find yourself needing to trigger this function manually, make sure you call it exactly once per cmd *cobra.Command.

Inputs: cmd where we can find the flags; args from the program; os.StdOut (pass this in to help with testing)

If there are no cobraFlagPrompt required flags registered at the cmd, this func does nothing.

Developer note: This code is automatically attached to PreRunE when you call MarkFlagRequired or MarkPersistentFlagRequired BUT if you set PreRunE *after* calling MarkFlagRequired or MarkPersistentFlagRequired, that will overwrite this PreRunE. In that scenario, you will need to manually call CobraFlagPromptPreRunE *at the very end of your PreRunE*. Because Cobra prefers PreRunE over PreRun (it's an if / else if), if you set your own PreRun after calling MarkFlagRequired or MarkPersistentFlagRequired then that PreRun will be ignored (unless you also cleared out PreRunE).

func MarkFlagRequired

func MarkFlagRequired(cmd *cobra.Command, name string) error

MarkFlagRequired causes the command to prompt the user if this flag is not provided as a command line argument.

func MarkPersistentFlagRequired

func MarkPersistentFlagRequired(cmd *cobra.Command, name string) error

func PromptForFlag

func PromptForFlag(flag *pflag.Flag, stdIn io.Reader, stdOut io.Writer) error

PromptForFlag prompts the user to enter a value for pflag. It can handle any type of flag supported by cobra.

The value received from the user is stored in the same way cobra stores it and is retrievable in the same way.