tucnak / climax

Climax is an alternative CLI with the human face

Climax

Climax is an alternative CLI that looks like Go command

Climax is a handy alternative CLI (command-line interface) for Go apps. It looks pretty much exactly like the output of the default go command and incorporates some fancy features from it. For instance, Climax does support so-called topics (some sort of Wiki entries for CLI). You can define some annotated use cases of some command that would get displayed in the help section of corresponding command also.

Why creating another CLI?

I didn't like existing solutions (e.g. codegangsta/cli | spf13/cobra) either for bloated codebase (I dislike the huge complex libraries) or poor output style / API. This project is just an another view on the subject, it has slightly different API than, let's say, Cobra; I find it much more convenient.

---

A sample application output, Climax produces:

Camus is a modern content writing suite.

Usage:

	camus command [arguments]

The commands are:

	init        starts a new project
	new         creates flavored book parts

Use "camus help [command]" for more information about a command.

Additional help topics:

	writing     markdown language cheatsheet
	metadata    intro to yaml-based metadata
	realtime    effective real-time writing

Use "camus help [topic]" for more information about a topic.

Here is an example of a trivial CLI application that does nothing, but provides a single string split-like functionality:

demo := climax.New("demo")
demo.Brief = "Demo is a funky demonstation of Climax capabilities."
demo.Version = "stable"

joinCmd := climax.Command{
	Name:  "join",
	Brief: "merges the strings given",
	Usage: `[-s=] "a few" distinct strings`,
	Help:  `Lorem ipsum dolor sit amet amet sit todor...`,

	Flags: []climax.Flag{
		{
			Name:     "separator",
			Short:    "s",
			Usage:    `--separator="."`,
			Help:     `Put some separating string between all the strings given.`,
			Variable: true,
		},
	},

	Examples: []climax.Example{
		{
			Usecase:     `-s . "google" "com"`,
			Description: `Results in "google.com"`,
		},
	},

	Handle: func(ctx climax.Context) int {
		var separator string
		if sep, ok := ctx.Get("separator"); ok {
			separator = sep
		}

		fmt.Println(strings.Join(ctx.Args, separator))

		return 0
	},
}

demo.AddCommand(joinCmd)
demo.Run()

Have fun!

climax's Issues

Iterators?

I am using this library in my application at https://github.com/parallelcointeam/pod - because it seems to be the most friendly and accessible CLI flags library that exists for Go. However, my application needs some 40-50 separate parameters in most instances of the use of climax and I used a function wrapper to condense the declarations, but the ctx.Is and ctx.Get functions chew up a whole if block per parameter.

I am looking at it, and for the reason that the function that reads off the values from the command line to overlay the configuration struct for the subcommands, I looked closer at the source and noted that the variable and non-variable types have exported names and thus can be iterated.

Of course it is not (that) difficult to write this, but I'm just posting this issue to suggest that it could have an iterator built into it if one defined a map type that contains the pointers to the variables, in the case of variables, and for the nonvariable case, could produce an array containing the handlers associated with the nonvariable flags to enable order sensitivity to the triggers so in the case of a subcommand that terminates, that it can do this from one map literal declaration and the iterator command, and automatically executes it.

I am immediately in the process of refactoring my code's use of this by using an iterator on these maps, I would think that probably the function could be quickly modified to become generic, using a map[string]interface{}, enable the automatic determination of intended variable type, assignment and resolution of the interface to direct explicit type. I am using JSON as the configuration file format also, so I can constrain the types to match JSON in as much as objects go to maps and arrays to slices, then bool, int, float and string.

If there is interest in having a PR for adding this iterator, let me know, and I probably can create an additional source file to go with the library that implements this.

Make it possible without subcommands

If i have only one command to execute, i dont need subcommands.

Feature request: add a "default" action

It would be cool if climax could execute a default climax.Command if no parameter is specified on the CLI.

Man page generation

PROTIP: See how it's done in hugo.

Min/max arguments count guards

We might want to add some min/max arguments count guards as some sugar.

If I try to use a flag in CLI that is not defined, gets a panic

If try tu run a small minimal app with climax, that doesn't have 't' flag defined, I get a panic:

 # ./stellar-stacy serve -t=3
panic: runtime error: invalid memory address or nil pointer dereference
[signal 0xb code=0x1 addr=0x40 pc=0x4814b6]

goroutine 1 [running]:
github.com/tucnak/climax.parseContext(0xc8200a0410, 0x1, 0x1, 0xc82007e260, 0x1, 0x1, 0x1, 0x0, 0x0)
    /home/foo/go/src/github.com/tucnak/climax/context.go:97 +0x496
github.com/tucnak/climax.Application.Run(0x78c890, 0x6, 0x7c1b80, 0x10, 0x821350, 0x13, 0xc8200ba180, 0x1, 0x1, 0x0, ...)
    /home/foo/go/src/github.com/tucnak/climax/application.go:117 +0xa19
main.main()
    /home/foo/go/src/myserver/myroot/stellar-stacy/main.go:21 +0x173

When launching it with a flag that exists, it works fine. The climax.Command structure I used is the one defined on the main github page.

Flags for default handler and global flags

Global flags could be used to define flags that'll be used by all commands. And flags parsing for default handler would be useful too.

Do you support subcommands?

I thought that groups would be subcommands, but it seems they are only for grouping them on the help page. Does climax currently support subcommands? If so, how?

Support list of values for a single flag.

it would be nicer to write:
command -i param1, param2 or command -i param1 param2
rather than:
command -i param1 -i param2

Lightweight command syntax

We need a super lightweight syntax of creating simple flag-less commands. Something like this would be great:

app := climax.New("appname")

app.Comm("command", "i am command", func (ctx climax.Context) {
    return 0;
});