clix

🔗 Table of Contents

• Features
• TODO
• Usage
• Example help output
• Generate Markdown
  • Example output
    • Application Options
    • Example Group
    • Logging Options
• Support & Assistance
• Contributing
• License

✨ Features

• go-flags wrapper, that handles parsing and decoding, with additional helpers. Uses Go 1.18's generics to allow embedding your own custom struct.
• Auto-generated logger, and auto-provided logger flags that:
  • allows users to switch between plain-text, colored/pretty, JSON output (and quiet for no output).
  • Allows configuring the level dynamically.
  • Uses the built-in debug flag to automatically change the logging level.
• Built-in --debug flag.
• Built-in --version flag that provides a lot of useful features:
  • Using Go 1.18's build metadata, the ability to use that as the version info, automatically using VCS information if available.
  • Printing dependencies and build flags.
  • Embedding useful links (support, repo, homepage, etc) in both version output, and help output.
  • Colored output!
• --generate-markdown flag (hidden) that allows generating markdown from the CLI's help information (see below!).
• Uses godotenv to auto-load environment variables from .env files, before parsing flags.
• Many flags to enable/disable functionality to suit your needs.

☑ TODO

• Generate commands/sub-commands/etc (example)
• Custom markdown formatting

⚙ Usage

go get -u github.com/lrstanley/clix@latest

Example:

package main

import (
 "github.com/apex/log"
 clix "github.com/lrstanley/clix"
)

var (
  cli = &clix.CLI[Flags]{
  Links: clix.GithubLinks("github.com/lrstanley/myproject", "master", "https://mysite.com"),
 }
 logger log.Interface
)

type Flags struct {
 EnableHTTP bool   `short:"e" long:"enable-http" description:"enable the http server"`
 File       string `env:"FILE" short:"f" long:"file" description:"some file that does something"`

 SubFlags struct {
  Username string `env:"USERNAME" short:"u" long:"username" default:"admin" description:"example username"`
  Password string `env:"PASSWORD" short:"p" long:"password" description:"example password"`
 } `group:"Example Group" namespace:"example" env-namespace:"EXAMPLE"`
}

func main() {
 // Initializes cli flags, and a pre-configured logger, based off user-provided
 // flags (e.g. --log.json, --log.level, etc). Also automatically handles
 // --version, --help, etc.
 cli.Parse()
 logger = cli.Logger

 logger.WithFields(log.Fields{
  "debug":     cli.Debug,
  "file_path": cli.Flags.File,
 }).Info("hello world")
}

Example help output

Below shows an example of a non-tagged revision of myproject. When using Git tags, the appropriate tag should be applied as the version, rather than (devel).

$ ./myproject --version
github.com/lrstanley/myproject :: (devel)
  build commit :: 2a00b14d2ff16b79ecbb2afc54f480c2c1e28172
    build date :: unknown
    go version :: go1.18.1 linux/amd64

helpful links:
      homepage :: https://myproject
        github :: https://github.com/lrstanley/myproject
        issues :: https://github.com/lrstanley/myproject/issues/new/choose
       support :: https://github.com/lrstanley/myproject/blob/master/.github/SUPPORT.md
  contributing :: https://github.com/lrstanley/myproject/blob/master/.github/CONTRIBUTING.md
      security :: https://github.com/lrstanley/myproject/security/policy

build options:
     -compiler :: gc
   CGO_ENABLED :: 1
    CGO_CFLAGS ::
  CGO_CPPFLAGS ::
  CGO_CXXFLAGS ::
   CGO_LDFLAGS ::
        GOARCH :: amd64
          GOOS :: linux
       GOAMD64 :: v1
           vcs :: git
  vcs.revision :: 2a00b14d2ff16b79ecbb2afc54f480c2c1e28172
      vcs.time :: 2022-04-26T00:08:11Z
  vcs.modified :: true

dependencies:
  h1:IVj9dxSeAC0CRxjM+AYLIKbNdCzAjUnsUjAp/td7kYo= :: ariga.io/atlas :: v0.3.8-0.20220424181913-f64001131c0e
  h1:Jlkg6X37VI/k5U02yTBB3MjKGniiBAmUGfA1TC1+dtU= :: ariga.io/entcache :: v0.0.0-20211014200019-283c566a429b
  h1:XE5df6hfIlK/YeRxY6ynRxoMKCqn2mIOcOjId8JrQN8= :: entgo.io/ent :: v0.10.2-0.20220424193633-04e0dc936be9
  h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo= :: github.com/agext/levenshtein :: v1.2.3
  h1:FHtw/xuaM8AgmvDDTI9fiwoAL25Sq2cxojnZICUU8l0= :: github.com/apex/log :: v1.9.0
  [...]

You can also use ./myproject --version-json for a more programmatic approach to the above information.

Generate Markdown

When using clix, you can generate markdown for your commands by passing the flag --generate-markdown, which is a hidden flag. This will print the markdown to stdout.

./<my-script> --generate-markdown > USAGE.md

Example output

Raw:

#### Application Options

| Environment vars | Flags               | Type   | Description                          |
| ---------------- | ------------------- | ------ | ------------------------------------ |
| -                | `-e, --enable-http` | bool   | enable the http server               |
| `FILE`           | `-f, --file`        | string | some file that does something        |
| -                | `-v, --version`     | bool   | prints version information and exits |
| `DEBUG`          | `-D, --debug`       | bool   | enables debug mode                   |

#### Example Group

| Environment vars   | Flags                    | Type   | Description                           |
| ------------------ | ------------------------ | ------ | ------------------------------------- |
| `EXAMPLE_USERNAME` | `-u, --example.username` | string | example username [**default: admin**] |
| `EXAMPLE_PASSWORD` | `-p, --example.password` | string | example password                      |

#### Logging Options

| Environment vars | Flags          | Type   | Description                                                                      |
| ---------------- | -------------- | ------ | -------------------------------------------------------------------------------- |
| `LOG_QUIET`      | `--log.quiet`  | bool   | disable logging to stdout (also: see levels)                                     |
| `LOG_LEVEL`      | `--log.level`  | string | logging level [**default: info**] [**choices: debug, info, warn, error, fatal**] |
| `LOG_JSON`       | `--log.json`   | bool   | output logs in JSON format                                                       |
| `LOG_PRETTY`     | `--log.pretty` | bool   | output logs in a pretty colored format (cannot be easily parsed)                 |

Generated:

Application Options

Example Group

Logging Options

🙋♂ Support & Assistance

• ❤ Please review the Code of Conduct for guidelines on ensuring everyone has the best experience interacting with the community.
• 🙋♂ Take a look at the support document on guidelines for tips on how to ask the right questions.
• 🐞 For all features/bugs/issues/questions/etc, head over here.

🤝 Contributing

• ❤ Please review the Code of Conduct for guidelines on ensuring everyone has the best experience interacting with the community.
• 📋 Please review the contributing doc for submitting issues/a guide on submitting pull requests and helping out.
• 🗝 For anything security related, please review this repositories security policy.

⚖ License

MIT License

Copyright (c) 2021 Liam Stanley <me@liamstanley.io>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Also located here