A note to readers:
I did my best to make this readme as comprehensive as possible but I strongly suggest reading the godocs detailed information on the internals of odin.

Installation | Usage | Examples | Contributing | In the Wild

A go-lang library to help build self documenting command line applications.

odin currently supports:

• Required Parameters
• Typed Flag/Option Parsing
• Flag Aliasing
• SubCommand DSL for creating complex CLI utils

get the package with:

go get github.com/jwaldrip/odin/cli

import it with:

import "github.com/jwaldrip/odin/cli"

or using a a package manager like Goop:

# Goopfile
github.com/jwaldrip/odin #v1.4.0

Creating a new CLI | Flags | Required Parameters | Freeform Parameters | Sub Commands | Self Documentation

cli.New(version string, description string, fn func(), params...)

Flags are optional parameters that can be specifed when running the command.

$ cmd --flag=value -g

Flags support a number of different types and can be defined by using a basic definition or pointer definition.

Basic Definitions are in the format of:

DefineTypeFlag(name string, defaultValue typedValue, usage string)

Pointer Definitions are in the format of:

var ptr TYPE
DefineTypeFlagVar(ptr, name string, defaultValue typedValue, usage string)

Flags also support aliases: aliases are always defined as a rune to limit them to one character.

FlagAlias(alias rune, flagName string)

package main

import (
	"fmt"

	"github.com/jwaldrip/odin/cli"
)

// CLI is the odin CLI
var app = cli.New("0.0.1", "my cli", func(c cli.Command){
	if c.Flag("gopher").Get() == true {
		fmt.Println("IS JUST GOPHERTASTIC!!!")
	} else {
		fmt.Println("Is pretty dandy")
	}
})

func init(){
	app.DefineBoolFlag("gopher", false, "is it gophertastic?")
	app.FlagAlias('g', "gopher")
}

func main(){
	app.Start()
}

$ mycli
Is pretty dandy

$ mycli --gopher
IS JUST GOPHERTASTIC!!!

$ mycli -g
IS JUST GOPHERTASTIC!!!

Commands can specify parameters that they require in the order they are passed. All parameter arguments are treated as string values.

They can be defined at CLI creation...

cli.New(version string, description string, fn func(Command), params ...string)

or at a later time...

app.DefineParams(params ...string)

Parameters can be accessed invidually...

	cmd.Param(name string) Value

or as a ValueMap where the name is the string key of the map.

	cmd.Params() ValueMap

Free form parameters are any parameters that remain after all parsing has completed.

To access them you can call them by their order...

cmd.Arg(0) Value

or just by getting them all as a slice

cmd.Args() ValueList

Sub commands can be defined in order to create chainable, complex command line utlilities.

Sub commands have all the same defintion methods as the root level command, with one caveat; they have a Parent() method that can be used to fetch parameters and flags from further up the command chain.

mycli.DefineSubCommand(name string, description string, fn func(Command), params ...string)

You would access the sub-command's flags and params just as you would a normal root level CLI.

cmd.Param("name")
cmd.Flag("name")

To access a parent commands just call:

cmd.Parent().Param("name")
cmd.Parent().Flag("name")

In addition to accesing the parent params via the Parent() you can instruct a sub command to inherit a flag from its parent.

example:

package main

import (
   "fmt"
	"github.com/jwaldrip/odin"
)

var app = cli.New("0.0.1", "sample command", func(Command){})

func init(){
	app.DefineStringFlag("user", "", "the user")
	subcmd := app.DefineSubCommand("action", "perform an action", func(c cli.Command){
		fmt.Println("the user is:", c.Flag("user"))
		fmt.Println("the action is:", c.Param("actionName"))
	})
	subcmd.DefineParams("actionName")
	subcmd.InheritFlag("user")
}

func main(){
	app.Start()
}

$ mycmd --user=jason action hello
the user is: jason
the action is: hello

Output is possible directly on the CLI and is prefered over using fmt. Available commands map to their fmt counterparts.

package main

import "github.com/jwaldrip/odin/cli"

app := cli.New("1.0.0", "my app", func(c cli.Command){
  c.Println("hello world")
  c.ErrPrintln("There was an error")
} 

Any io.Writer can be used as an output

outbuffer := bytes.NewBufferString("")
errbuffer := bytes.NewBufferString("")
app.SetStdOut(outbuffer)
app.SetStdErr(errbuffer)

Documentation is auto generated for all commands (main and sub). By Default a help flag --help and alias -h are defined on each command (unless overridden) to display usage to the end user.

Auto generated documentation for ./examples/greet-with:

$ greet-with -h
Usage:
  greet-with [options...] <greeting> <command> [arg...]

a simple tool to greet with

Options:
  -c, --color="blue"  # color the output (red, blue, green)
  -h, --help          # show help and exit
  -l, --loudly        # say loudly
  -v, --version       # show version and exit

Commands:
  to     greet a person

By Default a version flag --version and alias -v are defined on the main command (unless overridden), which will display the version specified when creating a new CLI.

Version for ./examples/greet-with:

$ greet-with -v
greet-with 1.0.0

Example CLIs can be found in ./examples

Here are some tools using Odin in the wild. Have your own you would like to plug? Submit a pull request!

• nitrous-io/tug
• jwaldrip/git-get
• Sam-Izdat/pogo

• Bash Completion
• Zsh Completion
• CLI Bootstrapping
• Param Inheritence

See CONTRIBUTING for details on how to contribute.