cli

README

cli

A minimal, command-oriented CLI package.

Features

• Very small, simple API.
• Uses standard flag package as much as possible.
• No external dependencies.
• Subcommands.
• Auto-generated help.

Install

go get -u go.coder.com/cli

Examples

See examples/ for more.

Simple CLI

package main

import (
    "flag"
    "fmt"

    "go.coder.com/cli"
)

type cmd struct {
    verbose bool
}

func (c *cmd) Run(fl *flag.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 *flag.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 (
    "flag"
    "fmt"

    "go.coder.com/cli"
)

type subcmd struct {
}

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

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

type cmd struct {
}

func (c *cmd) Run(fl *flag.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:
	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) 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 *flag.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

	// Hidden indicates that this command should not show up in it's parent's
	// subcommand help.
	Hidden bool
}

CommandSpec describes a Command's usage.

It should not list flags.

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 *flag.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.