The standard library flag package with its missing features

Overview

cmd

codecov GoDoc

Package cmd is a minimalistic library that enables easy sub commands with the standard flag library.

This library extends the standard library flag package to support sub commands and more features in a minimalistic and idiomatic API.

Features:

  • Sub commands.

  • Automatic bash completion.

  • Flag values definition and check.

  • Explicit positional arguments definition.

  • Automatic usage text.

Usage

Define a root command object using the New function. This object exposes the standard library's flag.FlagSet API, which enables adding flags in the standard way. Additionally, this object exposes the SubCommand method, which returns another command object. This objects also exposing the same API, enabling definition of flags and nested sub commands. The root object then have to be called with the Parse method, similarly to the flag.Parse call.

Principles

  • Minimalistic and flag-like.

  • Any flag that is defined in the base command will be reflected in all of its sub commands.

  • When user types the command, it starts from the command and sub commands, only then types the flags and then the positional arguments:

[command] [sub commands...] [flags...] [positional args...]
  • When a command defines positional arguments, all its sub commands has these positional arguments and thus can't define their own positional arguments.

  • When flag configuration is wrong, the program will panic.

Examples

Definition and usage of sub commands and sub commands flags.

package main

import (
	"fmt"

	"github.com/posener/cmd"
)

var (
	// Define root command with a single string flag. This object the familiar standard library
	// `*flag.FlagSet` API, so it can be used similarly.
	root  = cmd.New()
	flag0 = root.String("flag0", "", "root string flag")

	// Define a sub command from the root command with a single string flag. The sub command object
	// also have the same API as the root command object.
	sub1  = root.SubCommand("sub1", "first sub command")
	flag1 = sub1.String("flag1", "", "sub1 string flag")

	// Define a second sub command from the root command with an int flag.
	sub2  = root.SubCommand("sub2", "second sub command")
	flag2 = sub1.Int("flag2", 0, "sub2 int flag")
)

// Definition and usage of sub commands and sub commands flags.
func main() {
	// Parse command line arguments.
	root.ParseArgs("cmd", "sub1", "-flag1", "value")

	// Check which sub command was choses by the user.
	switch {
	case sub1.Parsed():
		fmt.Printf("Called sub1 with flag: %s", *flag1)
	case sub2.Parsed():
		fmt.Printf("Called sub2 with flag: %d", *flag2)
	}
}

Values

An example that shows how to use advanced configuration of flags and positional arguments using the predict package.

package main

import (
	"fmt"
	"github.com/posener/cmd"
	"github.com/posener/complete/v2/predict"
)

func main() {
	// Should be defined in global `var`.
	var (
		root = cmd.New()
		// Define a flag with valid values 'foo' and 'bar', and enforce the values by `OptCheck()`.
		// The defined values will be used for bash completion, and since the OptCheck was set, the
		// flag value will be checked during the parse call.
		flag1 = root.String("flag1", "", "first flag", predict.OptValues("foo", "bar"), predict.OptCheck())
		// Define a flag to accept a valid Go file path. Choose to enforce the valid path using the
		// `OptCheck` function. The file name will also be completed in the bash completion
		// processes.
		file = root.String("file", "", "file path", predict.OptPredictor(predict.Files("*.go")), predict.OptCheck())
		// Positional arguments should be explicitly defined. Define positional arguments with valid
		// values of 'baz' and 'buzz', and choose not to enforce these values by not calling
		// `OptCheck`. These values will also be completed in the bash completion process.
		args = root.Args("[args...]", "positional arguments", predict.OptValues("baz", "buzz"))
	)

	// Parse fake command line arguments.
	root.ParseArgs("cmd", "-flag1", "foo", "-file", "cmd.go", "buz", "bazz")

	// Test:

	fmt.Println(*flag1, *file, *args)
}

Output:

foo cmd.go [buz bazz]

Args

In the cmd package, positional arguments should be explicitly defined. They are defined using the Args or ArgsVar methods.

package main

import (
	"fmt"
	"github.com/posener/cmd"
)

func main() {
	// Should be defined in global `var`.
	var (
		root = cmd.New()
		// Positional arguments should be defined as any other flag.
		args = root.Args("[args...]", "positional arguments for command line")
	)

	// Parse fake command line arguments.
	root.ParseArgs("cmd", "v1", "v2", "v3")

	// Test:

	fmt.Println(*args)
}

Output:

[v1 v2 v3]

ArgsFn

An example of how to parse positional arguments using a custom function. It enables the advantage of using named variables such as src and dst as opposed to args[0] and args[1].

package main

import (
	"fmt"
	"github.com/posener/cmd"
)

func main() {
	// Should be defined in global `var`.
	var (
		root = cmd.New()
		// Define variables that will hold the command line positional arguments.
		src, dst string
	)

	// Define an `ArgsFn` that converts a list of positional arguments to the named variables. It
	// should return an error when the arguments are invalid.
	argsFn := cmd.ArgsFn(func(args []string) error {
		if len(args) != 2 {
			return fmt.Errorf("expected src and dst, got %d arguments", len(args))
		}
		src, dst = args[0], args[1]
		return nil
	})

	// Should be in `init()`.
	// Register the function in the root command using the `ArgsVar` method.
	root.ArgsVar(argsFn, "[src] [dst]", "positional arguments for command line")

	// Should be in `main()`.
	root.ParseArgs("cmd", "from.txt", "to.txt")

	// Test:

	fmt.Println(src, dst)
}

Output:

from.txt to.txt

ArgsInt

An example of defining int positional arguments.

package main

import (
	"fmt"
	"github.com/posener/cmd"
)

func main() {
	// Should be defined in global `var`.
	var (
		root = cmd.New()
		// Define a variable that will hold the positional arguments values. Use the `ArgsInt` type
		// to parse them as int.
		args cmd.ArgsInt
	)

	// Should be in `init()`.
	// Register the positional argument variable in the root command using the `ArgsVar` method.
	root.ArgsVar(&args, "[int...]", "numbers to sum")

	// Should be in `main()`.
	// Parse fake command line arguments.
	root.ParseArgs("cmd", "10", "20", "30")

	// Test:

	sum := 0
	for _, n := range args {
		sum += n
	}
	fmt.Println(sum)
}

Output:

60

ArgsN

An example of defining an exact number of positional arguments.

package main

import (
	"fmt"
	"github.com/posener/cmd"
)

func main() {
	// Should be defined in global `var`.
	var (
		root = cmd.New()
		// Define a variable that will hold positional arguments. Create the `ArgsStr` object with
		// cap=2 to ensure that the number of arguments is exactly 2.
		args = make(cmd.ArgsStr, 2)
	)

	// Should be in `init()`.
	// Register the positional argument variable in the root command using the `ArgsVar` method
	// (similar to the Var methods of the standard library).
	root.ArgsVar(&args, "[src] [dst]", "positional arguments for command line")

	// Should be in `main()`.
	// Parse fake command line arguments.
	root.ParseArgs("cmd", "from.txt", "to.txt")

	// Test:

	fmt.Println(args)
}

Output:

[from.txt to.txt]

Readme created from Go doc with goreadme

Issues
  • Print usage instead of panic for no arguments

    Print usage instead of panic for no arguments

    Previously, if no arguments were passed to the root command, a panic was triggered which in turn bypassed the error handling strategy. Also the provided message was not really helpful to the user.

    With this commit the usage is printed instead. Additionally, an error is returned which is correctly handled by the error handling strategy.

    opened by jangraefen 8
  • Add option to disable completion in usage

    Add option to disable completion in usage

    For some use-cases or operation systems, it might not be desirable to print usage information. That is why this commit introduces an option to disable completion information.

    This addresses issue #20

    opened by jangraefen 5
  • Add padding to sub command list

    Add padding to sub command list

    Having large variations in the length of sub commands could lead to inconsistent and ugly indention of the command synopses. This command fixes this by calculating the longest command name beforehand and padding all command names accordingly.

    opened by jangraefen 3
  • Cannot disable automatic bash autocompletion msg?

    Cannot disable automatic bash autocompletion msg?

    I appreciate the feature exists but can it be turned off? I glanced at the codebase and didn't see an option.

    I'm building an .exe for Windows and it makes no sense to be offering people Bash completion by default. (Ok, maybe for Cygwin, but still, not something I want in the -h output.)

    opened by darkvertex 3
  • Release for PR#22

    Release for PR#22

    Hey,

    I submitted #22 some kind ago and you were so kind to merge it :). Could you make a release/tag for that, so that I can actually pull my submitted changed back to my project? Thank you very much in advance.

    With kind regards :)

    opened by jangraefen 2
  • Inconsistent indention of sub commands

    Inconsistent indention of sub commands

    When having sub commands that have large differences in length, the usage might be formatted weirdly, since only a single tab is used to separate the command name from the synopsis.

    This could be fixed by padding all command names, taking the longest command name into consideration.

    I submitted the PR #22 to address this.

    opened by jangraefen 1
Releases(v1.3.4)
Owner
Eyal Posener
Eyal Posener
A collection of CLI argument types for the Go `flag` package.

flagvar A collection of CLI argument types for the flag package. import "github.com/sgreben/flagvar" Or just copy & paste what you need. It's public d

Sergey Grebenshchikov 38 Apr 19, 2022
Drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.

Description pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags. pflag is compatible with the GNU extensions to

Steve Francia 1.8k May 19, 2022
Golang library with POSIX-compliant command-line UI (CLI) and Hierarchical-configuration. Better substitute for stdlib flag.

cmdr cmdr is a POSIX-compliant, command-line UI (CLI) library in Golang. It is a getopt-like parser of command-line options, be compatible with the ge

hz 105 May 7, 2022
Flag is a simple but powerful command line option parsing library for Go support infinite level subcommand

Flag Flag is a simple but powerful commandline flag parsing library for Go. Documentation Documentation can be found at Godoc Supported features bool

null 120 Apr 1, 2022
Argparse for golang. Just because `flag` sucks

Golang argparse Let's be honest -- Go's standard command line arguments parser flag terribly sucks. It cannot come anywhere close to the Python's argp

Alexey Kamenskiy 422 May 16, 2022
CONTRIBUTIONS ONLY: A Go (golang) command line and flag parser

CONTRIBUTIONS ONLY What does this mean? I do not have time to fix issues myself. The only way fixes or new features will be added is by people submitt

Alec Thomas 3.2k May 11, 2022
Go binding configuration and command flag made easy✨✨

✨ Binding configuration and command flag made easy! ✨ You can use multiple keys tag to simplify the look like this (supported feature**): // single ta

Ii64人 13 Mar 2, 2022
The missing git branch --interactive

git branch-i I got cross that there's no git branch --interactive, so I made this. It's a very (very) simple curses-mode git branch/git checkout alter

Joel Auterson 3 Dec 17, 2021
A command line tool for filling missing metric values on Mackerel.

mackerel-null-bridge A command line tool for filling missing metric values on Mackerel. Description When sending error metrics, etc., you may be force

ikeda-masashi 0 Jan 11, 2022
A lightweight replacement for the standard fmt package, reduces binary size by roughly 400kb in a hello world

console This is a lightweight replacement for the fmt package, reduces the binary size by roughly 400kb in a hello world program. Please note: This pa

null 1 Nov 7, 2021
kcli: command line interface tool to interact with K8trics API server as well as manage its lifecycle

K8trics CLI (kcli) kcli is command line interface tool to interact with K8trics API server as well as manage its lifecycle. kcli can provision and dep

null 3 Dec 15, 2021
Go cmd utility that prints its command line arguments using strings.Join

Results This is an exercise of the book The Go Programming Language, by Alan A. A. Donovan and Brian Kernighan. Comparison between different versions

Santiago Rodriguez 0 Dec 18, 2021
A command-line interface for the Riak database through its HTTP API

Riakg Description Is a development oriented command line tool that enables navigation on buckets, keys and values of a Riak KV data store using it's H

cristian 4 May 10, 2022
The slightly more awesome standard unix password manager for teams

gopass Introduction gopass is a password manager for the command line written in Go. It supports all major operating systems (Linux, MacOS, BSD) as we

Gopass 4.6k May 15, 2022
Read from standard input and output a Haags translation of the given input.

haags Read from standard input and output a Haags translation of the given input. Building make && sudo make install You may also run go build on syst

Kees van Voorthuizen 3 Sep 13, 2021
An open-source GitLab command line tool bringing GitLab's cool features to your command line

GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with git and your code without switching

Clement Sam 1.9k May 14, 2022
oc CLI plugin to interact with Helm features provided by the OpenShift Console

OpenShift provides support for managing the lifecycle of Helm charts. This capability is limited primarily to the Web Console. This plugin enables the management of Helm charts similar to using the standalone Helm CLI while offloading much of the work to OpenShift.

Andrew Block 18 Oct 11, 2021
CLI program for SEO 301 & 302 url rewrites in fastly with more magento features soon to come

Magento-Fastly Table of Contents Magento-Fastly Development & Testing Install fastly cli Features Installation Usage Development & Testing To test thi

null 1 Oct 29, 2021
Template repository for testing CLI features of applications written in Go

Go CLI testing example This repository provides a template on how to create a testable CLI applications in Go language. As an example, this applicatio

Mateusz Gozdek 7 Nov 18, 2021