README
¶
Build command line interfaced applications fast and easy.
Ideally suited for novice Developers.
Quick view
import "gopkg.in/kataras/cli.v0"
func main() {
cli.NewApp("httpserver", "converts current directory into http server", "0.0.1").
Flag("directory", "C:/users/myfiles", "specify a directory to convert").
Run(func(cli.Flags) error {
return nil
})
}
Features
- Simple to use, create a working app in one line
- Easy API, no need to read any docs, just type
cli.via your favorite editor and your hand will select the correct function to do the job - Auto command naming alias
- App has commands, each command can have subcommands, the same commands and their flags can be registered and used over multiple Apps
- Understands the go types automatically, no more
*string - Monitor, optionally, each command through App's action listener
- Help command automation
- Share app's screen and output with any type of
io.Writer
Installation
The only requirement is the Go Programming Language.
$ go get -u gopkg.in/kataras/cli.v0
Getting started
// NewApp creates and returns a new cli App instance
//
// example:
// app := cli.NewApp("iris", "Command line tool for Iris web framework", "0.0.1")
NewApp(name string, description string, version string) *App
package main
import (
"fmt"
"gopkg.in/kataras/cli.v0"
)
func main() {
app := cli.NewApp("httpserver", "converts current directory into http server", "0.0.1")
// $executable -d, $executable --directory $the_dir
app.Flag("directory", "C:/users/myfiles", "specify a current working directory")
// $executable listen
listenCommand := cli.Command("listen", "starts the server")
// $executable listen -h, $executable listen --host $the_host
listenCommand.Flag("host", "127.0.0.1", "specify an address listener")
// $executable listen -p, $executable listen --port $the_port
listenCommand.Flag("port", 8080, "specify a port to listen")
// $executable listen -d, $executable listen --dir $the_dir
listenCommand.Flag("dir", "", "current working directory")
// $executable listen -r , $executable listen --req $the_req
listenCommand.Flag("req", nil, "a required flag because nil default given")
listenCommand.Action(listen)
app.Command(listenCommand) //register the listenCommand to the app.
app.Run(run)
}
// httpserver -d C:/web/site
func run(args cli.Flags) error {
// if the app has flags then 'run' will do its job as action, not as monitor
fmt.Printf("Executing from global app's flag -d/-directory = %s\n ", args.String("directory"))
// you can also run a command by code, listenCommand.Execute()
return nil
}
// httpserver listen -h mydomain.com
func listen(args cli.Flags) error {
fmt.Printf("Executing from command listen with Host: %s and Port: %d \n",
args.String("host"), args.Int("port"))
return nil
}
Note that: --help (or -help, help, -h) global flag is automatically used and displays help message.
FAQ
If you'd like to discuss this package, or ask questions about it, feel free to
- Explore these questions.
- Post an issue or idea here.
- Navigate to the Chat.
Versioning
Current: 0.0.4
Read more about Semantic Versioning 2.0.0
- http://semver.org/
- https://en.wikipedia.org/wiki/Software_versioning
- https://wiki.debian.org/UpstreamGuide#Releases_and_Versions
People
The author of cli is @kataras.
Contributing
If you are interested in contributing to the cli project, please make a PR.
License
This project is licensed under the MIT License.
License can be found here.
Documentation
¶
Overview ¶
Package cli helps you create command line interfaces with the Go Programming Language
Index ¶
Constants ¶
const Version = "0.0.4"
Version is the current version number of the cli package
Variables ¶
var Output = os.Stdout // the output is the same for all Apps, atm.
Output the common output of the cli app, defaults to os.Stdout
Functions ¶
Types ¶
type Action ¶
Action the command's listener
func DefaultAction ¶
DefaultAction is the default action where no command's action is defined
type App ¶
App is the container of all commands, subcommands, flags and your application's name and description it builds the full help message and other things useful for your app example of initialize an cli.App in the init(): var app *cli.App init the cli app func init(){ app = cli.NewApp("iris", "Command line tool for Iris web framework", Version) // version command app.Command(cli.Command("version", "\t prints your iris version").
Action(func(cli.Flags) error { app.Printf("%s", iris.Version); return nil }))
// create command createCmd := cli.Command("create", "creates & runs a project based on the iris-contrib/examples, to a given directory").
Flag("dir", workingDir, "the directory to install the sample package").
Flag("type", "basic", "creates a project based on the -t package. Currently, available types are 'basic' & 'static'").
Action(create)
// run command runAndWatchCmd := cli.Command("run", "runs and reload on source code changes, example: iris run main.go").Action(runAndWatch)
// register the commands app.Command(createCmd) app.Command(runAndWatchCmd) }
func main() {
// run the application
app.Run(func(cli.Flags) error {
return nil
})
}
func NewApp ¶
NewApp creates and returns a new cli App instance
example: app := cli.NewApp("iris", "Command line tool for Iris web framework", Version)
func (*App) Flag ¶
Flag creates a new flag based on name, defaultValue (if empty then the flag is required) and a usage
func (App) HasCommands ¶
HasCommands returns true if the app has registered commands, otherwise false
func (*App) Printf ¶
Printf just like fmt.Printf but prints to the application's output, which is the global Output
func (App) Run ¶
Run executes the App, must be called last it receives an action too, like the commands but this action can be empty but if this action returns an error then the execution panics. Its common usage is when you need to 'monitor' the application's commands flags and check if a command should execute based its name or no (the app's command is a flag to the app's action function)
type Cmd ¶
type Cmd struct {
Name string
Description string
// Flags are not the arguments was given by the user, but the flags that developer sets to this command
Flags Flags
Subcommands Commands
// contains filtered or unexported fields
}
Cmd is the command struct which contains the command's Name, description, any flags, any subcommands and mostly its action listener
func Command ¶
Command builds and returns a new *Cmd, no app-relative. Note that the same command can be used by multiple applications. example: createCmd := cli.Command("create", "creates a project to a given directory").
Flag("offline", false, "set to true to disable the packages download on each create command").
Flag("dir", workingDir, "$GOPATH/src/$dir the directory to install the sample package").
Flag("type", "basic", "creates a project based on the -t package. Currently, available types are 'basic' & 'static'").
Action(create)
app = cli.NewApp("iris", "Command line tool for Iris web framework", Version)
app.Command(createCmd) // registers the command to this app
returns itself
func (*Cmd) Action ¶
Action is the most important function declares a command's action/listener example: createCmd := cli.Command("create", "creates a project to a given directory").
Flag("dir", workingDir, "the directory to install the sample package").
Action(func(flags cli.Flags){ /* here the action */ })
returns itself
func (*Cmd) Execute ¶
Execute calls the Action of the command and the subcommands returns true if this command has been executed successfully
func (*Cmd) Flag ¶
Flag sets a flag to the command example: createCmd := cli.Command("create", "creates a project to a given directory").
Flag("dir", "the default value/path is setted here", "$GOPATH/src/$dir the directory to install the sample package").Flag(...).Action(...)
returns the Cmd itself
type Flag ¶
type Flag struct {
Name string
Default interface{}
Usage string
Value interface{}
Raw *goflags.FlagSet
}
Flag is the command's action's flag, use it by flags.Get("myflag").Alias()/.Name/.Usage/.Raw/.Value
type Flags ¶
type Flags []*Flag
Flags the flags passed to the command's Action
func (Flags) Bool ¶
Bool returns the flag's value as bool by it's name, if not found returns false panics on !bool
func (Flags) Int ¶
Int returns the flag's value as int by it's name, if can't parse int then returns -1 panics on !int
func (Flags) String ¶
String returns the flag's value as string by it's name, if not found returns empty string "" panics on !string
Source Files