cli

README

cli

A minimal, command-oriented CLI package.

Features

• Very small, simple API.
• Support for POSIX flags.
• Only external dependency is spf13/pflag.
• Subcommands.
• Auto-generated help.

Install

go get -u go.coder.com/cli

Examples

See examples/ for more.

Simple CLI

package main

import (
    "fmt"

    "github.com/spf13/pflag"
    "go.coder.com/cli"
)

type cmd struct {
    verbose bool
}

func (c *cmd) Run(fl *pflag.FlagSet) {
    if c.verbose {
        fmt.Println("verbose enabled")
    }
    fmt.Println("we run")
}

func (c *cmd) Spec() cli.CommandSpec {
    return cli.CommandSpec{
        Name:  "simple-example",
        Usage: "[flags]",
        Desc:  `This is a simple example of the cli package.`,
    }
}

func (c *cmd) RegisterFlags(fl *pflag.FlagSet) {
    fl.BoolVar(&c.verbose, "v", false, "sets verbose mode")
}

func main() {
    cli.RunRoot(&cmd{})
}

renders a help like

Usage: simple-example [flags]

This is a simple example of the cli package.

simple-example flags:
	-v	sets verbose mode	(false)

Subcommands

package main

import (
    "fmt"

    "github.com/spf13/pflag"
    "go.coder.com/cli"
)

type subcmd struct {
}

func (c *subcmd) Run(fl *pflag.FlagSet) {
    fmt.Println("subcommand invoked")
}

func (c *subcmd) Spec() cli.CommandSpec {
    return cli.CommandSpec{
        Name:  "sub",
        Usage: "",
        Aliases: []string{"s"},
        Desc:  `This is a simple subcommand.`,
    }
}

type cmd struct {
}

func (c *cmd) Run(fl *pflag.FlagSet) {
    // This root command has no default action, so print the help.
    fl.Usage()
}

func (c *cmd) Spec() cli.CommandSpec {
    return cli.CommandSpec{
        Name:  "subcommand",
        Usage: "[flags]",
        Desc:  `This is a simple example of subcommands.`,
    }
}

func (c *cmd) Subcommands() []cli.Command {
    return []cli.Command{
        &subcmd{},
    }
}

func main() {
    cli.RunRoot(&cmd{})
}

renders a help like

Usage: subcommand [flags]

This is a simple example of subcommands.

Commands:
	s,sub -	This is a simple subcommand.

Documentation

Overview

Package cli provides a thin CLI abstraction around the standard flag package. It is minimal, command-struct-oriented, and trades off "power" for flexibility and clarity at the caller level.

It pretends that Go's single dash (-flag) support doesn't exist, and renders helps with --.

Optional interface adherence can be asserted with a statement like

var _ interface {
	cli.Command
	cli.FlaggedCommand
	cli.ParentCommand
} = new(rootCmd)

Index

• func Run(cmd Command, args []string, parent string)
• func RunRoot(cmd Command)
• type Command
• type CommandSpec
  • func (c CommandSpec) HasAliases() bool
  • func (c CommandSpec) ShortDesc() string
• type FlaggedCommand
• type ParentCommand

Functions

func Run

func Run(cmd Command, args []string, parent string)

Run sets up flags, helps, and executes the command with the provided arguments.

parents is the list of parent commands. E.g the parent for `sail run hello` would be `sail run`.

Use RunRoot if this package is managing the entire CLI.

func RunRoot

func RunRoot(cmd Command)

RunRoot calls Run with the process's arguments.

Types

type Command

type Command interface {
	// Spec returns metadata about the command.
	Spec() CommandSpec
	// Run invokes the command's main routine with parsed flags.
	Run(fl *pflag.FlagSet)
}

Command describes a command or subcommand.

type CommandSpec

type CommandSpec struct {
	// Name is the name of the command.
	// It should be the leaf name of the entire command. E.g `run` for the full
	// command `sail run`.
	Name string
	// Usage is the command's usage string.
	// E.g "[flags] <path>"
	Usage string
	// Desc is the description of the command.
	// The first line is used as an abbreviated description.
	Desc string
	// RawArgs indicates that flags should not be parsed, and they should be deferred
	// to the command.
	RawArgs bool
	// Hidden indicates that this command should not show up in it's parent's
	// subcommand help.
	Hidden bool
	// Aliases contains a list of alternative names that can be used for a particular command.
	Aliases []string
}

CommandSpec describes a Command's usage.

It should not list flags.

func (CommandSpec) HasAliases

func (c CommandSpec) HasAliases() bool

HasAliases evaluates whether particular command has any alternative names.

func (CommandSpec) ShortDesc

func (c CommandSpec) ShortDesc() string

ShortDesc returns the first line of Desc.

type FlaggedCommand

type FlaggedCommand interface {
	// RegisterFlags lets the command register flags which be sent to Handle.
	RegisterFlags(fl *pflag.FlagSet)
}

FlaggedCommand is an optional interface for commands that have flags.

type ParentCommand

type ParentCommand interface {
	Subcommands() []Command
}

ParentCommand is an optional interface for commands that have subcommands.

A ParentCommand may pass itself into children as it creates them in order to pass high-level configuration and state.