Fully featured Go (golang) command line option parser with built-in auto-completion support.

Video Demo: https://youtu.be/1ZGyIkC5shM

• Quick overview
• Examples
  • Simple script
  • Program with multiple commands separated in multiple packages
  • Directed Acyclic Graph Build System
• DAG Build System
• Features
• How to install it
• Dependencies
• Introduction
• Automatically generate help
• Autocompletion
• Options
  • Boolean options
  • Options with String arguments
  • Options with Integer arguments
  • Options with Floating point arguments
  • Options with array arguments
  • Options with Key Value arguments
  • Incremental option
  • Options with optional arguments
  • Stop parsing options when -- is passed
  • Allow passing options and non-options in any order
  • Allow pass through
  • Fail on unknown
  • Warn on unknown
  • Option Modifiers (ModifyFn)
    • Aliases
    • Description
    • Required options
    • Read option value from environment variable
    • Help argument name hint
    • Suggested values
    • Valid values
    • Set option as called
• Operation Modes: How to handle single dash '-' options
  • Normal Mode (default)
  • Bundling Mode
  • Enforce Single Dash Mode
• Command behaviour
• ROADMAP
  • Possible Env Variable Roadmap
• License

1. See a detailed video demonstration: https://youtu.be/1ZGyIkC5shM

2. Define your command line specification:

   package main
   
   import (
   	"context"
   	"errors"
   	"fmt"
   	"io"
   	"log"
   	"os"
   
   	"github.com/DavidGamba/go-getoptions"
   )
   
   var Logger = log.New(os.Stderr, "", log.LstdFlags)
   
   func main() {
   	os.Exit(program(os.Args))
   }
   
   func program(args []string) int {
   	ctx, cancel, done := getoptions.InterruptContext()
   	defer func() { cancel(); <-done }()
   
   	opt := getoptions.New()
   	opt.Self("myscript", "Simple demo script")
   	opt.Bool("debug", false, opt.GetEnv("DEBUG"))
   	opt.Int("greet", 0, opt.Required(), opt.Description("Number of times to greet."))
   	opt.StringMap("list", 1, 99, opt.Description("Greeting list by language."))
   	opt.Bool("quiet", false, opt.GetEnv("QUIET"))
   	opt.HelpSynopsisArg("<name>", "Name to greet.")
   	opt.SetCommandFn(Run)
   	opt.HelpCommand("help", opt.Alias("?"))
   	remaining, err := opt.Parse(args[1:])
   	if err != nil {
   		fmt.Fprintf(os.Stderr, "ERROR: %s\n", err)
   		return 1
   	}
   	if opt.Called("quiet") {
   		Logger.SetOutput(io.Discard)
   	}
   
   	err = opt.Dispatch(ctx, remaining)
   	if err != nil {
   		if errors.Is(err, getoptions.ErrorHelpCalled) {
   			return 1
   		}
   		fmt.Fprintf(os.Stderr, "ERROR: %s\n", err)
   		if errors.Is(err, getoptions.ErrorParsing) {
   			fmt.Fprintf(os.Stderr, "\n"+opt.Help())
   		}
   		return 1
   	}
   	return 0
   }
   
   func Run(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
   	// Get arguments and options
   	name, _, err := opt.GetRequiredArg(args)
   	if err != nil {
   		return err
   	}
   	greetCount := opt.Value("greet").(int)
   	list := opt.Value("list").(map[string]string)
   
   	Logger.Printf("Running: %v", args)
   
   	// Use the int variable
   	for i := 0; i < greetCount; i++ {
   		fmt.Printf("Hello %s, from go-getoptions!\n", name)
   	}
   
   	// Use the map[string]string variable
   	if len(list) > 0 {
   		fmt.Printf("Greeting List:\n")
   		for k, v := range list {
   			fmt.Printf("\t%s=%s\n", k, v)
   		}
   	}
   
   	return nil
   }

3. Call it:

   Show help

   $ ./myscript help
   NAME:
       myscript - Simple demo script
   
   SYNOPSIS:
       myscript --greet <int> [--debug] [--help|-?] [--list <key=value>...]...
                [--quiet] <name>
   
   ARGUMENTS:
       <name>                   Name to greet.
   
   REQUIRED PARAMETERS:
       --greet <int>            Number of times to greet.
   
   OPTIONS:
       --debug                  (default: false, env: DEBUG)
   
       --help|-?                (default: false)
   
       --list <key=value>...    Greeting list by language. (default: {})
   
       --quiet                  (default: false, env: QUIET)

   Show errors

   $ ./myscript
   ERROR: Missing required parameter 'greet'

   Show errors

   $ ./myscript -g
   ERROR: Missing argument for option 'greet'!

   Show errors

   $ ./myscript -g 3
   ERROR: Missing <name>
   SYNOPSIS:
       myscript --greet <int> [--debug] [--help|-?] [--list <key=value>...]...
                [--quiet] <name>

   Use of int option

   $ ./myscript -g 3 David
   2024/01/04 23:25:14 Running: [David]
   Hello David, from go-getoptions!
   Hello David, from go-getoptions!
   Hello David, from go-getoptions!

   Use of bool option

   $ ./myscript -g 1 David --quiet
   Hello David, from go-getoptions!

   Use of map option

   $ ./myscript -g 0 David -l en='Hello World' es='Hola Mundo'
   2024/01/04 23:27:00 Running: [David]
   Greeting List:
   	en=Hello World
   	es=Hola Mundo

For an overview of the Directed Acyclic Graph Build System see ./dag/README.adoc

• Built in auto completion. A single line of bash is all it takes.

  complete -o default -C my-go-program my-go-program

  Zshell is also supported, by exporting ZSHELL=true in your environment and using bashcompinit.

• Allow passing options and non-options (arguments) in any order.

• Support for --long options.

• Support for short (-s) options with flexible behaviour (see the Operation Modes: How to handle single dash '-' options section for details):

  • Normal (default)

  • Bundling

  • SingleDash

• Called() method indicates if the option was passed on the command line.

• Multiple aliases for the same option. e.g. help, man.

• CalledAs() method indicates what alias was used to call the option on the command line.

• Synopsis and option list automated help.

• Boolean, String, Int, Float64, Slice and Map type options.

• Options with Array arguments. The same option can be used multiple times with different arguments. The list of arguments will be saved into an Slice.

• Options with array arguments and multiple entries.

  For example, instead of writing: color --r 10 --g 20 --b 30 --next-option or color --rgb 10 --rgb 20 --rgb 30 --next-option the input could be: color --rgb 10 20 30 --next-option

• When using integer array options with multiple arguments, positive integer ranges are allowed.

  For example, Instead of writing: csv --columns 1 2 3 or csv --columns 1 --columns 2 --columns 3 The input could be: csv --columns 1..3

• Options with Key Value arguments. This allows the same option to be used multiple times with arguments of key value type.

  For example: rpmbuild --define name=myrpm --define version=123

• Options with key value arguments and multiple entries.

  For example, instead of writing: connection --server hostname=serverIP --server port=123 --client hostname=localhost --client port=456 the input could be: connection --server hostname=serverIP port=123 --client hostname=localhost port=456

• Supports command line options with '='.

  For example: You can use --string=mystring and --string mystring.

• Allows passing arguments to options that start with dash - when passed after equal.

  For example: --string=--hello and --int=-123.

• Supports passing -- to stop parsing arguments (everything after will be left in the remaining []string).

• Options with optional arguments. If the default argument is not passed the default is set.

  For example: You can call --int 123 which yields 123 or --int which yields the given default.

• Allows abbreviations when the provided option is not ambiguous.

  For example: An option called build can be called with --b, --bu, --bui, --buil and --build as long as there is no ambiguity. In the case of ambiguity, the shortest non ambiguous combination is required.

• Support for the lonesome dash "-". To indicate, for example, when to read input from STDIO.

• Incremental options. Allows the same option to be called multiple times to increment a counter.

• Supports case sensitive options. For example, you can use v to define verbose and V to define Version.

• Support indicating if an option is required and allows overriding the default error message.

• Errors and Help Strings exposed as public variables to allow overriding them for internationalization.

• Supports program commands and subcommands (when a command is passed a command function is triggered to handle the command logic).

• Built in opt.Dispatch function calls commands and propagates context, options, arguments and cancellation signals.

• Multiple ways of managing unknown options:

  • Fail on unknown (default).

  • Warn on unknown.

  • Pass through, allows for commands and can be combined with Require Order.

• Require order: Allows for commands. Stop parsing arguments when the first non-option is found. When mixed with Pass through, it also stops parsing arguments when the first unmatched option is found.

• Set options by reading Environment Variables. Precedence is CLI option over Env Var over Default.

1. Get it from github:

   go get github.com/DavidGamba/go-getoptions

2. Then import it:

   import "github.com/DavidGamba/go-getoptions" // As getoptions

3. Enjoy!

Go 1.16+

Only the last two versions of Go will be supported.

Option parsing is the act of taking command line (CLI) arguments and converting them into meaningful structures within the program.

First declare a getoptions instance:

Then declare the options you want to parse:

Optionally, define option modifiers:

You can also define arguments:

Define the function for the program:

If no function is defined and opt.Dispatch is called, the program will show a help message with any commands or subcommands.

Define any commands and their options, arguments and functions:

After defining options and commands declare the help command, it must be the last one defined.

Parse the CLI arguments (or any []string):

Finally, call dispatch which will call the proper command function for the given arguments:

Dispatch requires a context.Context to be passed which can be used to propagate cancellation signals or configuration values.

A built in helper to create a context with cancellation support (os.Interrupt, syscall.SIGHUP, syscall.SIGTERM) is provided:

The actual functions running the business logic are the CommandFn functions set with the SetCommandFn.

The CommandFn function signature is:

This function will receive the context, the parsed options and the remaining arguments.

Read the received options from the opt variable.

Read the received arguments from the args slice. Additionally, use the opt.GetRequiredArg (with int and float64 variants) to simplify handling required arguments and providing error messages.

For a proper extended man page for your program consider asciidoctor that can generate manpages written in the Asciidoc markup.

For the built-in help, you can add a description to your program:

• opt.Self("", "This is a program description")

For options help ensure you add option descriptions and argument names.

• opt.Description("This is a string option")

• opt.ArgName("mystring")

The help command needs to be defined after all options, commands and subcommands.

opt.HelpCommand("help", opt.Alias("?"))

When calling the help command, you get the full help. Optionally you can print only given sections of the Help.

For example:

Or through a helper:

In the code above, if there is no argument passed, the GetRequiredArg will print an error plus the synopsis:

The error return is getoptions.ErrorHelpCalled which signals the help is already printed. The dispatch error handling can handle this error and not print and additional error message.

Another helpful error to check for is getoptions.ErrorParsing, as shown above, which indicates there was a problem parsing the CLI arguments. This can be used, to print the help only in cases where the user didn’t enter valid CLI options or arguments.

The built in help shows default values and environment variables when available.

It separates COMMANDS, ARGUMENTS, REQUIRED PARAMETERS and OPTIONS into separate sections.

For example, the following is a script using the built in help:

And below is the output of the automated help of a program with multiple commands:

Any built-in string in go-getoptions, like titles, is exposed as a public variable so it can be overridden for internationalization.

To enable bash autocompletion, add the following line to your bash profile:

For the above to work, the program must be in the PATH. Otherwise:

To enable zsh autocompletion, add the following line to your zsh profile:

The ZSHELL="true" export is required because bash and zsh have different ways of handling autocompletion and there is no reliable way to detect which shell is being used.

If testing completion in the CLI, you might require to first clean the completion entry that complete auto generates when hitting Tab twice:

complete -r ./my-go-program 2>/dev/null

When providing these as scripts that users source but not add into their profile you can use the following sourceme.bash script:

Then when the users go into the directory and run source sourceme.bash the autocompletion will be enabled.

Notice how so far only long options (options starting with double dash --) have been mentioned. There are 3 main ways to handle short options (options starting with only one dash -).

The behaviour for long options (options starting with double dash --) is consistent across operation modes. The behaviour for short options (options starting with only one dash -) depends on the operation mode. The sections below show the different operation modes.

This section describes how the parser resolves ambiguities between the program and the command.

Given a definition like:

There is an option at the parent, profile and one at the command, password. Passing --p <arg> is ambiguous and results in an error. At minimum, --pr <arg> and --pa <arg> are required.

Given a definition like:

There is an option at the parent, profile and one at the command, password with alias p. Passing --p <arg> at the parent results in the parent opt.Parse call to leave the --p <arg> option unhandled and leave it in the remaining slice. The opt.Dispatch call gets the -p <arg> option and throws an error. At minimum, --pr <arg> is required to call profile at the parent and command options must be passed after the command declaration.

For example, the calls below is correct:

But the following one is incorrect:

• Generate compilation errors for commands without a defined CommandFn.

• Create new error description for errors when parsing integer ranges (1..3).

• Case insensitive matching.

• prefix and prefix_pattern. The string that starts options. Defaults to "--" and "-" but could include "/" to support Win32 style argument handling.

• Allow grouping commands so they can have a different order other than alphabetical in the help output.

• Some Windows tests fail because the binary name includes .exe at the end. Update test suite to accommodate for Windows.

• Introduce a opt.NoArgs so there are no [<args>] listed in the help output.

• Add CustomCompletionFn before release figure out how to have ways to have custom completions with different engines for arg1 and arg2.

• Figure out how to have custom completions for option values.

• Add OptionGroup to allow grouping options in the help output.

• Document CustomCompletion and ValidValues in autocompletion section.

• Mark optional as required in subcommand.

This file is part of go-getoptions.

Copyright © 2015-2024 David Gamba Rios

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.