acmd

README

acmd

Simple, useful and opinionated CLI package in Go. For config loader see aconfig

Rationale

Popular CLI libraries (or better frameworks) have too large and unclear API, in most cases, you just want to define commands for your CLI application and run them without additional work. This package does this by providing a small API, good defaults and clear code.

Features

• Simple API.
• Dependency-free.
• Clean and tested code.
• Command aliases.
• Auto suggesting command.
• Builtin help and version commands.

Install

Go version 1.17+

go get github.com/cristalhq/acmd

Example

cmds := []acmd.Command{
	{
		Name:        "now",
		Description: "prints current time",
		ExecFunc: func(ctx context.Context, args []string) error {
			fmt.Printf("now: %s\n", now.Format("15:04:05"))
			return nil
		},
	},
	{
		Name:        "status",
		Description: "prints status of the system",
		ExecFunc: func(ctx context.Context, args []string) error {
			// do something with ctx :)
			return nil
		},
	},
}

// all the acmd.Config fields are optional
r := acmd.RunnerOf(cmds, acmd.Config{
	AppName:        "acmd-example",
	AppDescription: "Example of acmd package",
	Version:        "the best v0.x.y",
	// Context - if nil `signal.Notify` will be used
	// Args - if nil `os.Args[1:]` will be used
	// Usage - if nil default print will be used
})

if err := r.Run(); err != nil {
	r.Exit(err)
}

See examples: examples_test.go.

Documentation

See these docs or GUIDE.md for more details.

License

MIT License.

Documentation

Overview

Package acmd is a simple, useful and opinionated CLI package in Go.

See: https://github.com/cristalhq/acmd

Index

• Variables
• func AutocompleteFor(cmds []Command) (string, error)
• func HasHelpFlag(flags []string) bool
• type Command
• type Config
• type ErrCode
  • func (e ErrCode) Error() string
• type Exec
• type FlagsGetter
• type Runner
  • func RunnerOf(cmds []Command, cfg Config) *Runner
  • func (r *Runner) Exit(err error)
  • func (r *Runner) Run() error

Examples

• Runner

Variables

var (
	ErrNoArgs = errors.New("no args provided")
)

Functions

func AutocompleteFor

func AutocompleteFor(cmds []Command) (string, error)

func HasHelpFlag

func HasHelpFlag(flags []string) bool

HasHelpFlag reports whether help flag is presented in args.

Types

type Command

type Command struct {
	// Name of the command, ex: `init`
	Name string

	// Alias is an optional short second name, ex: `i`.
	Alias string

	// Description of the command.
	Description string

	// ExecFunc represents the command function.
	// Use Exec if you have struct implementing this function.
	ExecFunc func(ctx context.Context, args []string) error

	// Exec represents the command function.
	// Will be used only if ExecFunc is nil.
	Exec Exec

	// Subcommands of the command.
	Subcommands []Command

	// IsHidden reports whether command should not be show in help. Default false.
	IsHidden bool

	// FlagSet is an optional field where you can provide command's flags.
	// Is used for autocomplete. Works best with https://github.com/cristalhq/flagx
	FlagSet FlagsGetter
}

Command specifies a sub-command for a program's command-line interface.

type Config

type Config struct {
	// AppName is an optional name for the app, if empty os.Args[0] will be used.
	AppName string

	// AppDescription is an optional description. default is empty.
	AppDescription string

	// PostDescription of the command. Is shown after a help.
	PostDescription string

	// Version of the application.
	Version string

	// Output is a destionation where result will be printed.
	// Exported for testing purpose only, if nil os.Stdout is used.
	Output io.Writer

	// Context for commands, if nil context based on os.Interrupt and syscall.SIGTERM will be used.
	Context context.Context

	// Args passed to the executable, if nil os.Args[1:] will be used.
	Args []string

	// Usage of the application, if nil default will be used.
	Usage func(cfg Config, cmds []Command)

	// VerboseHelp if "./app help -v" is passed, default is false.
	VerboseHelp bool
}

Config for the runner.

type ErrCode

type ErrCode int

ErrCode is a number to be returned as an exit code.

func (ErrCode) Error

func (e ErrCode) Error() string

type Exec

type Exec interface {
	ExecCommand(ctx context.Context, args []string) error
}

Exec represents a command to run.

type FlagsGetter

type FlagsGetter interface {
	Flags() *flag.FlagSet
}

FlagsGetter returns flags for the command. See examples.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner of the sub-commands.

Example

package main

import (
	"context"
	"flag"
	"fmt"
	"net/http"
	"os"
	"time"

	"github.com/cristalhq/acmd"
)

var nopUsage = func(cfg acmd.Config, cmds []acmd.Command) {}

func main() {
	testOut := os.Stdout
	testArgs := []string{"someapp", "now", "--times", "3"}

	const format = "15:04:05"
	now, _ := time.Parse(format, "10:20:30")

	cmds := []acmd.Command{
		{
			Name:        "now",
			Description: "prints current time",
			ExecFunc: func(ctx context.Context, args []string) error {
				fs := flag.NewFlagSet("some name for help", flag.ContinueOnError)
				times := fs.Int("times", 1, "how many times to print time")
				if err := fs.Parse(args); err != nil {
					return err
				}

				for i := 0; i < *times; i++ {
					fmt.Printf("now: %s\n", now.Format(format))
				}
				return nil
			},
			FlagSet: &commandFlags{},
		},
		{
			Name:        "status",
			Description: "prints status of the system",
			ExecFunc: func(ctx context.Context, args []string) error {
				req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://www.githubstatus.com/", http.NoBody)
				resp, err := http.DefaultClient.Do(req)
				if err != nil {
					return err
				}
				defer resp.Body.Close()
				// TODO: parse response, I don't know
				return nil
			},
		},
	}

	r := acmd.RunnerOf(cmds, acmd.Config{
		AppName:         "acmd-example",
		AppDescription:  "Example of acmd package",
		PostDescription: "Best place to add examples",
		Version:         "the best v0.x.y",
		Output:          testOut,
		Args:            testArgs,
		Usage:           nopUsage,
	})

	if err := r.Run(); err != nil {
		panic(err)
	}

}

type generalFlags struct {
	IsVerbose bool
	Dir       string
}

func (c *generalFlags) Flags() *flag.FlagSet {
	fs := flag.NewFlagSet("", flag.ContinueOnError)
	fs.BoolVar(&c.IsVerbose, "verbose", false, "should app be verbose")
	fs.StringVar(&c.Dir, "dir", ".", "directory to process")
	return fs
}

type commandFlags struct {
	generalFlags
	File string
}

func (c *commandFlags) Flags() *flag.FlagSet {
	fs := c.generalFlags.Flags()
	fs.StringVar(&c.File, "file", "input.txt", "file to process")
	return fs
}

Output:

now: 10:20:30
now: 10:20:30
now: 10:20:30

func RunnerOf

func RunnerOf(cmds []Command, cfg Config) *Runner

RunnerOf creates a Runner.

func (*Runner) Exit

func (r *Runner) Exit(err error)

Exit the application depending on the error. If err is nil, so successful/no error exit is done: os.Exit(0) If err is of type ErrCode: code from the error is returned: os.Exit(code) Otherwise: os.Exit(1).

func (*Runner) Run

func (r *Runner) Run() error

Run commands.