clio

README

clio

clio is a declarative cli tool. It takes care of parsing args, ensuring required args are present, and a help command, leaving the rest to you.

Usage

Install clio, then use the CLI struct to define the root of your CLI application. The Command struct is used to define sub commands. See examples/sub_commands for an example.

The SetupHandler field in both structs is where you'll setup flags, arguments, and the handler for each command. The function body is where you should call c.AddFlag, c.AddStringFlag, or c.AddArgument. The function should then return a function which is what will be called when your command is executed. See examples/arguments for an example.

Then in your main function, call your_cli.Run().

Validation

As the configuration is validated when running your cli, it's important to validate the config before you build to ensure you don't build a binary that will fail due to validation errors. There are two options for validating your clio config.

1. Using the clio cli tool and running clio validate <pacage_path> <Cli_name>. Your cli variable needs to be exported.
2. Creating a second binary and in it's main function call your_cli.Validate() instead. You can then run this binary to validate your CLI configuration.

Troubleshooting

If encountering issues will developing your application, clio can log more of it's internal information which may or may not help you identify where things may be going awry. There are two tags which enhance logging for clio: clio_debug and clio_trace. clio_trace can be noisey, so use with care.

These tags should never be used to build a release version of your binary.

go run -tags clio_debug <path/to/your/main.go>

Documentation

Index

• type ArgumentConfig
• type Cli
  • func (c Cli) Run()
  • func (c Cli) Validate()
• type Command
• type Context
  • func (c *Context) AddArgument(config ArgumentConfig) *string
  • func (c *Context) AddFlag(config FlagConfig) *bool
  • func (c *Context) AddStringFlag(config FlagConfig) *string
• type FlagConfig
• type Handler
  • func HelpHandler(c *Context) Handler
  • func OnlySubCommandHandler(c *Context) Handler
• type Setup

Examples

• Cli.Run
• Cli.Validate

Types

type ArgumentConfig

type ArgumentConfig struct {
	Name        string // Required.
	Description string // Optional. Used for the help command.
	Required    bool   // Optional. Default: false. Required arguments cannot be added after optional ones.
}

Configure a positional argument in clio.

type Cli

type Cli struct {
	Name              string    // Required.
	Description       string    // Optional. Used for the built in help command to give your users information about your application.
	SubCommands       []Command // Optional.
	SetupHandler      Setup     // Optional. Define the function executed during the execution of your CLI. Defaults to setup command with HelpHandler.
	EnableHelpCommand bool      // Optional. Default: false. Enable clio's builtin help command.
}

The core struct for your CLI application.

func (Cli) Run

func (c Cli) Run()

Call Cli.Run() in your main function to execute your CLI.

Example

package main

import (
	"github.com/probablyanewt/fire/pkg/clio"
	"github.com/probablyanewt/fire/pkg/loggo"
)

var myCli = clio.Cli{
	Name: "mycli",
	SetupHandler: func(clio *clio.Context) clio.Handler {
		return func() error {
			loggo.Info("Hello world")
			return nil
		}
	},
}

func main() {
	myCli.Run()
}

func (Cli) Validate

func (c Cli) Validate()

Call Cli.Validate() in a main function, to validate your CLI configuration.

As the Run function also validates the CLI before executing, you should call this before building your CLI into a binary, in order to ensure it is error free.

Example

package main

import (
	"github.com/probablyanewt/fire/pkg/clio"
	"github.com/probablyanewt/fire/pkg/loggo"
)

var myCli = clio.Cli{
	Name: "mycli",
	SetupHandler: func(clio *clio.Context) clio.Handler {
		return func() error {
			loggo.Info("Hello world")
			return nil
		}
	},
}

func main() {
	myCli.Validate()
}

type Command

type Command struct {
	Name         string    // Required.
	Description  string    // Optional. Used for the built in help command to give your users information about your Command. The first sentence will be used as a snippet to be displayed in the help command of the parent command.
	SubCommands  []Command // Optional.
	SetupHandler Setup     // Optional. Define the function executed during the execution of your Command. Defaults to setup with HelpHandler.
}

Use Command to define SubCommands for your CLI.

type Context

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

func (*Context) AddArgument

func (c *Context) AddArgument(config ArgumentConfig) *string

Add a positional argument to the command. Returns a reference to the location where the argument will be stored.

func (*Context) AddFlag

func (c *Context) AddFlag(config FlagConfig) *bool

Add a flag to the command. Returns a reference to the lcoation where the flag will be stored.

func (*Context) AddStringFlag

func (c *Context) AddStringFlag(config FlagConfig) *string

Add a string flag to the command. Returns a reference to the lcoation where the flag will be stored.

type FlagConfig

type FlagConfig struct {
	Name        string // Required.
	Description string // Optional. Used for the help command.
	Alias       byte   // Optional.
}

Configure a flag in clio.

type Handler

type Handler func() error

The function signature executed when the command is called.

func HelpHandler

func HelpHandler(c *Context) Handler

HelpHandler will put this command in help only mode. So if this command is exectued, it will instead just show the help page for this command instead. Use this function as the value for SetupHandler.

func OnlySubCommandHandler

func OnlySubCommandHandler(c *Context) Handler

OnlySubCommandHandler will put this command into sub command only mode. So if this command is exectued, it will instead error informing the user that a sub command is required. Use this function as the value for SetupHandler.

type Setup

type Setup func(c *Context) Handler