Command line interface framework in Go.

Installing

go get github.com/aSquidsBody/[email protected]

Usage

Commands can be templated using the Command struct

// example-commands.go
package main

import "github.com/aSquidsBody/gocli"

var ExampleCommand = gocli.Command{
    Name: "command",
    LongDesc: "An example command",
    ShortDesc: "",
    // ...more configurations
}

A behavior can be defined for the command

// example-commands.go
package main

import (
    "fmt"
    "github.com/aSquidsBody/gocli"
)

var ExampleCommand = gocli.Command{
    Name: "command",
    LongDesc: "An example command",
    ShortDesc: "",
    Behavior: ExampleBehavior
}

func ExampleBehavior(ctx gocli.Context) {
    fmt.Println("Hello world!")
}

The command can be used as an entrypoint for the CLI

// main.go
package main

import "github.com/aSquidsBody/gocli"

func main() {
    // init the cli
    cli := gocli.NewCli(&ExampleCommand)

    // run the cli
    cli.Exec()
}

The build the go executable with either

go build -o <executable-name>

or

go install

See a more in-depth example in example.go.

API Documentation

Command

A configuration template for CLI commands

Command struct Fields

Command.Name

Required

Type: String

Name of the command (as referenced in the CLI)

Command.Behavior

Required

Type: func(ctx Context) void

A function which preforms the behavior of the command.

Command.ShortDesc

Optional

Type: String

Description that is printed when "--help" is included in the parent command.

Command.LongDesc

Optional

Type: String

Description that is printed when "--help" is included in the command.

Command.Options

Optional

Type: *[]Option

Command.Options is a pointer to a list of Option structs for the command

Command.Argument

Optional

Type: Argument

An Argument struct to define argument for the command

Context

Context is the object that is passed to Command.Behavior when a command is run. It is populated with CLI arguments.

Context.Referrer

Type: string

The collective name of the commands which built the context. For example, if the user ran root child1 child2 [OPTIONS] in the command prompt, then the Context was built in the child2 command; however, the Referrer field would equal root child1 child2

Context.Children

Type: []*Command

An array of pointers to Command configurations for each sub-command

Context.Options

Type: []Option

An array of Option configurations for the command

Context.StrArgs

Type: []string

An array of unprocessed CLI args

Context.Args

Type: map[string]interface{}

A map of arguments that have been parsed and type-casted to their respective types. An argument defaults to the value of if it is not included in the cli command

[METHOD] Context.HelpStr()

Parameters: None

Prints the help string for the command

Option

A configuration template for cli options

Option.Type

Required

Type: string

Indicates the expected datatype of the option. Can be "bool", "string", "int", and "float"

Option.Description

Optional

Type: string

A description of the option

Option.Short

Optional

Type: string

A short name for the option. The "-" should be omitted, e.g. if you want to configure -v as a short name for the option, then set Short to v.

Option.Long

Optional

Type: string

A long name for the option. The "--" should be omitted, e.g. if you want to configure --verbose as a long name for the option, then set Long to verbose.

Option.Required

Optional

Type: bool

Indicates whether the option is required (true) or optional (false). Defaults to false.

BashResult

BashResult.Stdout

Type: string

The stdout of a bash command.

BashResult.Stderr

Type: string

The stderr of a bash command.

BashResult.Err

Type: error

An error which may have occurred during the bash command. If the bash command fails (exits with non-zero code), then BashResult.Err will not be

[Function] Bash

Parameters: cmd string

Returns: BashResult

Runs a bash command.

[Function] BashStream

Parameters:

• cmd string
• stdout bool
• stderr bool

Returns: BashResult

Runs a bash command. If stdout is true, the shell's stdout is copied in real time to the terminal. If stderr is true, the shell's stderr is copied in real time to the terminal.

[Function] BashStreamLabel

Parameters:

• cmd string
• stdout bool
• stderr bool
• label string

Returns: BashResult

Runs a bash command in the same manner as BashStream with the addition behavior of prepending label to each line of the streamed stdout/stderr.