moul.io/climan

climan

:smile: CLI manager library, heavily inspired by ffcli.

This package is originally based on peterbourgon's ff package (Apache2 License).

It implements small changes that don't fit with the original's author Goals and Non-goals.

Changes include:

• Adding an optional Command.FlagSetBuilder callback to configure commands and subcommands dynamically and support sharing the same flag targets.
• Using flag.ContinueOnError by default instead of flag.ExitOnError.
• Printing usage instead of an returning an error if a command does not implements an Exec func.
• Use a different DefaultUsageFunc.

Example

import (
    "context"
    "flag"
    "fmt"
    "log"
    "os"

    "moul.io/climan"
)

func Example() {
    var opts struct {
        Debug bool
    }

    root := &climan.Command{
        Name:       "example",
        ShortUsage: "example [global flags] <subcommand> [flags] [args...]",
        ShortHelp:  "example's short help",
        LongHelp:   "example's longer help.\nwith more details.",
        FlagsBuilder: func(fs *flag.FlagSet) {
            fs.BoolVar(&opts.Debug, "debug", opts.Debug, "debug mode")
        },
        Exec: func(ctx context.Context, args []string) error {
            fmt.Println("args", args)
            return nil
        },
        Subcommands: []*climan.Command{
            &climan.Command{
                Name: "sub",
            },
        },
        // Options: []climan.Option{climan.WithEnvVarPrefix("EXAMPLE")},
    }
    if err := root.Parse(os.Args[1:]); err != nil {
        log.Fatal(fmt.Errorf("parse error: %w", err))
    }

    if err := root.Run(context.Background()); err != nil {
        log.Fatal(fmt.Errorf("run error: %w", err))
    }
}

Usage

TYPES

type Command struct {
    Name         string
    Exec         func(context.Context, []string) error
    FlagsBuilder func(fs *flag.FlagSet)
    Subcommands  []*Command
    ShortUsage   string
    ShortHelp    string
    LongHelp     string

    // Has unexported fields.
}

func (c *Command) Parse(args []string) error

func (c *Command) Run(ctx context.Context) error

Install

Using go

go get moul.io/climan

Releases

See https://github.com/moul/climan/releases

Contribute

I really welcome contributions. Your input is the most precious material. I'm well aware of that and I thank you in advance. Everyone is encouraged to look at what they can do on their own scale; no effort is too small.

Everything on contribution is sum up here: CONTRIBUTING.md

Dev helpers

Pre-commit script for install: https://pre-commit.com

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Manfred Touron 🚧 📖 ⚠️ 💻

moul-bot 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

Stargazers over time

License

© 2021 Manfred Touron

Licensed under the Apache License, Version 2.0 (LICENSE-APACHE) or the MIT license (LICENSE-MIT), at your option. See the COPYRIGHT file for more details.

SPDX-License-Identifier: (Apache-2.0 OR MIT)