👏 Applause - A clap.rs ripoff (/port) for Go

A shameless port of Rust's clap.rs to Go. If you know clap, you know Applause.

Why?

Clap.rs is the best CLI argument parser. Period. But it's in Rust. This is the same thing, but for Go.

Features

What works:

• Builder pattern API (just like clap)
• Positional args and flags (-s, --long)
• Subcommands
• Type parsing (string, int, float, bool)
• Validation
• Argument groups
• Multiple values
• Default values
• Environment variables
• Auto-generated help

What doesn't (yet):

• Shell completions
• Derive macros (Go doesn't have macros)
• Man page generation
• Colors in terminal output

Installation

go get github.com/JamesPatrickGill/applause

Usage

Basic example:

package main

import (
    "fmt"
    "os"
    "github.com/JamesPatrickGill/applause"
)

func main() {
    cmd := applause.NewCommand("myapp").
        Version("1.0.0").
        About("Does things").
        Arg(applause.NewArg("input").
            Help("Input file").
            Required(true)).
        Arg(applause.NewArg("verbose").
            Short("v").
            Long("verbose").
            Help("Verbose output"))

    matches := cmd.GetMatchesFrom(os.Args)

    input, _ := matches.GetPositional(0)
    verbose := matches.IsPresent("verbose")

    // Do stuff
}

Examples

Subcommands

cmd := applause.NewCommand("git").
    Subcommand(
        applause.NewCommand("add").
            Arg(applause.NewArg("files").Multiple(true)),
    ).
    Subcommand(
        applause.NewCommand("commit").
            Arg(applause.NewArg("message").Short("m").Long("message")),
    )

Validation

cmd.Arg(applause.NewArg("port").
    Short("p").
    ValueType(applause.IntType).
    Validator(applause.Range(1, 65535)))

Real-world Example

See examples/yarn - a toy yarn CLI clone showing nested subcommands, multiple args, validation, etc.

cd examples/yarn
go run main.go add lodash --dev
go run main.go install --frozen-lockfile

API

Commands

• NewCommand(name) - Create command
• .Version(v) - Set version
• .About(text) - Set description
• .Arg(arg) - Add argument
• .Subcommand(cmd) - Add subcommand
• .Group(group) - Add argument group

Arguments

• NewArg(name) - Create argument
• .Short(c) - Short flag (-v)
• .Long(name) - Long flag (--verbose)
• .Help(text) - Help text
• .Required(bool) - Is required
• .ValueType(type) - int/float/bool/string
• .Multiple(bool) - Accept multiple
• .Default(val) - Default value
• .EnvVar(name) - Env var fallback
• .Validator(v) - Add validator

Types

• StringType (default)
• IntType
• FloatType
• BoolType

Validators

• Range(min, max) - Number range
• MinLength(n) - Min string length
• MaxLength(n) - Max string length
• OneOf(values...) - Enum
• Pattern(regex) - Regex match
• Custom(func) - Custom function

Should you use this?

Yes if:

• You write Rust by choice but Go for a paycheck
• You've used clap.rs and miss it
• You think Cobra is overly complicated for what it does
• You want your CLI code to actually look like the rest of your Go code
• You believe CLIs should be built with method chaining, not struct tags

No if:

• You're happy with Cobra (good for you, seriously)
• You need shell completions today (use Cobra)
• You want something "official" or "enterprise" (use Cobra)
• You need colors in your terminal (we'll get there... maybe)

Advanced

Custom Validators

cmd.Arg(applause.NewArg("email").
    Validator(applause.Custom(func(v string) error {
        if !strings.Contains(v, "@") {
            return fmt.Errorf("not an email")
        }
        return nil
    })))

Error Handling

matches, errs := cmd.TryGetMatchesFrom(os.Args)
if len(errs) > 0 {
    // Handle errors
}

Environment Variables

cmd.Arg(applause.NewArg("token").
    EnvVar("API_TOKEN").
    Required(true))

TODO

• Shell completions
• Colors
• Man pages
• Localization
• Config files

Contributing

PRs welcome. Keep it clap-like.

License

MIT