README ¶
cli-ng
An easy to use CLI library for the Go language
Motivation
cli-ng
or "CLI Next Generation" is a library intended to allow developers to quickly and concisely build powerful CLI programs. It implements a fully-custom options parser to allow it to easily handle many sub-commands. It may also be used in Single Binary mode to allow a single executable to provide several programs.
Usage
Root Command
At the highest level, a cmd.Root
specifies an cli-ng
executable. You can assign it all the fields shown here and more. Running the executable is as simple as calling Root.Run()
.
var Root = &cmd.Root {
Name: "example",
Short: "An example CLI to show off cli-ng",
Version: "1.0.0",
Copyright: "© 2017-2021 Bryan T. Meyers <root@datadrake.com>",
License: "Licensed under the Apache License, Version 2.0",
}
func main() {
Root.Run()
}
Sub Command
A cli-ng
executable is composed of one or more sub-commands, each with their own purpose and Run function. Sub-commands also support aliases for less typing. Adding a sub-command is a simple as registering it with cmd.Register()
during initialization. Your cmd.Root
will automatically know all about it. If cmd.Root
is run without specifying a sub-command, a Usage message is printed with a listing of all sub-commands and any global flags.
func init() {
cmd.Register(&Sub1)
}
var Sub1 = cmd.Sub {
Name: "sub1",
Alias: "s1",
Short: "An example sub-command for showing off cli-ng",
Run: Sub1Run,
}
func Sub1Run(r *cmd.Root, s *cmd.Sub) {
// do stuff
}
Flags
Flags can be specified both for cmd.Root
and cmd.Sub
using nothing but a struct and some tags. The short
tag specifies a single-character switch for the flag (e.g. -v). The long
tag specifies a multi-character name for a flag (e.g. --verbose). Flags must specify at least one of the short
or long
tags, but both are not required. The desc
tag provides a short description for the flag. Boolean flags do not accept an argument. If they are specified, the flag is set to true
. Other types of flags that supported include:
- string
- float32, float64
- int, int8, int16, int32, int64
- uint, uint8, uint16, uint32, uint64
These types of flags can be set by specifying an additional argument, without an =
(e.g. -v 8).
Structs MUST be assigned by pointer.
type GlobalFlags struct {
Danger bool `long:"--yes-i-am-really-sure-this-is-what-i-want" desc:"All safeties are off"`
Debug bool `short:"D" desc:"Enable debug logging (e.g. -v 8)"`
Verbose uint8 `short:"v" long:"verbose" desc:"Enable verbose logging"`
}
var Root = &cmd.Root {
Name: "example",
Short: "An example CLI to show off cli-ng",
Version: "1.0.0",
Copyright: "© 2017-2021 Bryan T. Meyers <root@datadrake.com>",
License: "Licensed under the Apache License, Version 2.0",
Flags: &GlobalFlags{},
}
Arguments
Arguments can be specified for each cmd.Sub
by using nothing but a struct and some tags. The desc
tag provides a short description of the argument. The following types of arguments are supported:
- string
- float32, float64
- int, int8, int16, int32, int64
- uint, uint8, uint16, uint32, uint64
The last value in the struct may also be a Slice of any of these types. By default, this slice must contain at least one element. Setting the zero
struct tag allows the slice to be empty.
Structs MUST be assigned by pointer.
type Sub1Args struct {
Arg1 string `desc:"First argument"`
Args []uint8 `zero:"true" desc:"Zero or more byte-sized integers"`
}
var Sub1 = cmd.Sub {
Name: "sub1",
Alias: "s1",
Short: "An example sub-command for showing off cli-ng",
Args: &Sub1Args{},
Run: Sub1Run,
}
Single Binary Mode
Often, Go binaries can be quite large compared to some languages. There are many good reasons for this that are the subject of discussion for some other time. cli-ng
, however, is able to help with this problem by supporting something called Single Binary mode. In Single Binary mode, cli-ng
can act as one or more different executables, each with their own flags and arguments. This approach is similar to the one used by busybox
.
When cmd.Root.Single
is set to true
, sub-commands are now treated as executable names. In other words, the name provided by os.Args[0]
will be expected to match a sub-command. This is easily achieved by symlinking to the executable with links of those names. cmd.GenSingleLinks
provides this functionality as a sub-command for ease of use. In this mode, cmd.GenManPages
will also behave accordingly, generating docs for the sub-commands without the name of cmd.Root
as a prefix.
Built-in Sub-Commands
The following sub-commands are provided as a part of cli-ng
's cmd
package. The may be optionally registered before running the cmd.Root
.
cmd.Help
This is by far the most useful sub-command. Adding it to your program allows users to type help
or ?
and then the name or alias of a cmd.Sub
for a Usage message.
cmd.GenManPages
The gen-man-pages
sub-command can be used to generate man pages for each of the sub-commands. It is Hidden
(cmd.Sub.Hidden
is set to true
) and will not show up in any Usage messages unless called by help
. Like help
, some sub-commands may wish to omit their man page. This can be easily achieved by setting cmd.Sub.SkipMan
to true
.
cmd.GenSingleLinks
The gen-single-links
sub-command can be used to generate symlinks for each of the sub-commands when running in Single
mode. It is Hidden
(cmd.Sub.Hidden
is set to true
) and will not show up in any Usage messages unless called by help
. It also will not show up as a man page. gen-single-links
accepts a single argument for the directory to install the links to. It expects that the single-binary is installed there as well.
cmd.Version
THe version
sub-command prints out the name and version of the program, followed by optional copyright and license notices.
Projects Using cli-ng
- github.com/alecbcs/lookout
- github.com/arkenproject/ait
- github.com/DataDrake/cuppa
- github.com/DataDrake/go-base (Single Binary)
- github.com/DataDrake/proc-maps
- github.com/DataDrake/static-cling
- github.com/DataDrake/todo
- github.com/EbonJaeger/mcsmanager
- github.com/getsolus/ferryd
- github.com/getsolus/usysconf
License
Copyright 2017-2021 Bryan T. Meyers root@datadrake.com
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation ¶
There is no documentation for this package.