cli

README

cli - A minimal CLI command package using pflag

This package contains the implementation for a minimal opinionated flags framework similar to spf13/cobra. It all centers around the cli.Command type but provides less functionality.

The package is low-dependency, only relying on the pflag package, to provide -- unix flag options.

This package is used in:

• github.com/go-bridget/mig - database migration tooling,
• github.com/titpetric/atkins - a local command runner for CI,
• github.com/titpetric/vuego-cli - a vuego template engine docs server, CLI,
• github.com/titpetric/etl - database agnostic tooling to interface databases
• github.com/titpetric/exp - experimental CLI tooling, notably go-fsck

It's existed in some form for many years and I kept rewriting the CLIs to the next best thing, this exists for me to stop worring about flags like not an already solved problem. Reuse what works.

• no environment handling (put it in default value with os.Getenv)
• provide defaults with or without env support
• scoped flagset bindings with Bind()
• error handling, usage, help

The benchmark are tools like git, docker, docker compose, go where there is a mixture of command arguments (git status, git pull, ...) and flags like -d, --force. This package is the minimal shed in the back, the "cli package we have at home".

Documentation

Overview

CLI package

This package contains the implementation for a minimal opinionated flags framework similar to spf13/cobra. It all centers around the `cli.Command` type but provides less functionality.

To create a new CLI application:

```go app := cli.NewApp("mig") app.AddCommand("version", version.Name, version.New)

if err := app.Run(); err != nil {
        return err
}

```

The `version.New` is a `func() *cli.Command`.

The Command type defines Name and Title as strings, equivalent to cobra `Command.Use` (Name) and `Command.Long` (Title). There is no equivalent of `Command.Short`.

The API choices are different, cobra's `AddCommand` took a command, and the command type was passed into Run().

The cli package creates a `CommandInfo` with AddCommand, and then calls the constructor of the `*Command` type. The type must have Run filled, and can implement Bind(*FlagSet) to read in CLI flags.

The Run function is context aware, supporting observability.

Index

• func ParseWithFlagSet(fs *FlagSet, args []string) error
• type App
  • func NewApp(name string) *App
  • func (app *App) AddCommand(name, title string, constructor func() *Command)
  • func (app *App) FindCommand(commands []string, fallback string) (*Command, error)
  • func (app *App) HasCommand(name string) bool
  • func (app *App) Help()
  • func (app *App) HelpCommand(fs *FlagSet, command *Command)
  • func (app *App) ParseCommands(args []string) []string
  • func (app *App) Run() error
  • func (app *App) RunWithArgs(args []string) error
• type Command
• type CommandInfo
• type FlagSet

Examples

• App

Functions

func ParseWithFlagSet

func ParseWithFlagSet(fs *FlagSet, args []string) error

ParseWithFlagSet parses flags and environment variables for a scoped FlagSet.

Types

type App

type App struct {
	Name           string
	DefaultCommand string
	// contains filtered or unexported fields
}

App is the cli entrypoint.

Example

package main

import (
	"context"
	"fmt"

	"github.com/titpetric/cli"
)

func main() {
	app := cli.NewApp("mig")

	app.AddCommand("version", "Print version information", func() *cli.Command {
		var verbose bool

		return &cli.Command{
			Name:  "version",
			Title: "Print version information",
			Bind: func(fs *cli.FlagSet) {
				fs.BoolVarP(&verbose, "verbose", "v", false, "enable verbose output")
			},
			Run: func(ctx context.Context, args []string) error {
				if verbose {
					fmt.Println("mig version 1.2.3 (commit abcdef)")
				} else {
					fmt.Println("mig version 1.2.3")
				}
				return nil
			},
		}
	})

	// In a real program you would call:
	//     _ = app.Run()
	//
	// For examples/tests, invoke RunWithArgs directly.
	_ = app.RunWithArgs([]string{"version"})

}

Output:

mig version 1.2.3

func NewApp

func NewApp(name string) *App

NewApp creates a new App instance.

func (*App) AddCommand

func (app *App) AddCommand(name, title string, constructor func() *Command)

AddCommand adds a command to the app.

func (*App) FindCommand

func (app *App) FindCommand(commands []string, fallback string) (*Command, error)

FindCommand finds a command for the app.

func (*App) HasCommand

func (app *App) HasCommand(name string) bool

HasCommand checks if a command exists in the app.

func (*App) Help

func (app *App) Help()

Help prints out registered commands for app.

func (*App) HelpCommand

func (app *App) HelpCommand(fs *FlagSet, command *Command)

HelpCommand prints out help for a specific command.

func (*App) ParseCommands

func (app *App) ParseCommands(args []string) []string

ParseCommands cleans up args[], returning only commands. If no commands are detected, DefaultCommand is returned.

func (*App) Run

func (app *App) Run() error

Run passes os.Args without the command name to RunWithArgs().

func (*App) RunWithArgs

func (app *App) RunWithArgs(args []string) error

RunWithArgs is a cli entrypoint which sets up a cancellable context for the command.

type Command

type Command struct {
	Name    string
	Title   string
	Default bool
	Usage   func() string
	Bind    func(*FlagSet)
	Run     func(context.Context, []string) error

	// Flags is a separate FlagSet containing only command-specific
	// flags (excluding root-level flags like --help). It is populated
	// automatically by App.RunWithArgs and can be used to print
	// command flag defaults without the --help flag.
	Flags *FlagSet
}

Command is an individual command.

type CommandInfo

type CommandInfo struct {
	Name  string
	Title string
	New   func() *Command
}

CommandInfo is the constructor info for a command

type FlagSet

type FlagSet = pflag.FlagSet

FlagSet is here to prevent pflag leaking to imports.