clix

🔗 Table of Contents

• Features
• Usage
• Example help output
• Generate Markdown
• Migrating to v2
• Support & Assistance
• Contributing
• License

✨ Features

clix is a kong wrapper, that handles parsing of struct tags, unmarshalling config files, DI, and more. Includes builtin plugins for:

• Logging (JSON, pretty printed, logging to a file, or discarding) using log/slog.
  • Exposed handler and logger which you can use as a base for any additional logging configuration.
  • Change logging levels easily (and automatically when using --debug).
• Versioning (--version, --version-json) which aids in printing version information.
  • Exposes 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.
• Markdown (generate markdown from the CLI's help information). See example 1 and example 2. See below for more details.
• Built-in --debug flag.
• Parsing and loading of dotenv files (.env), with dynamic variable expansion.

clix is configurable, so all of the above can be turned on/off, with a reasonable default configuration that should work for most basic apps.

⚙ Usage

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

Example:

package main

import (
	"github.com/lrstanley/clix/v2"
)

type Flags struct {
	Name string `name:"name" default:"world" help:"name to print"`
}

var cli = clix.NewWithDefaults[Flags]()

func main() {
	logger := cli.GetLogger()

	if cli.Debug {
		logger.Debug("thinking really hard...")
	}

	logger.Info("hello", "name", cli.Flags.Name)
}

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 --help
Usage: myproject <command> [flags]

github.com/user/project :: (devel)

    build commit :: 063bc199778e1ae617c35b70608e4ef104d6ce31
      build date :: 2025-10-06T04:35:02Z
      go version :: go1.25.1 linux/amd64

Flags:
  -h, --help            Show context-sensitive help.
  -v, --version         prints version information and exits
      --version-json    prints version information in JSON format and exits
      --name="world"    name to print
  -D, --debug           enables debug mode

Logging flags
  --log.level="info"    logging level (none: disables logging) ($LOG_LEVEL)
  --log.json            output logs in JSON format ($LOG_JSON)
  --log.path=STRING     path to log file (disables stderr logging) ($LOG_PATH)

And version output:

$ ./myproject --version
github.com/user/project :: (devel)
|  build commit :: 063bc199778e1ae617c35b70608e4ef104d6ce31
|    build date :: 2025-10-06T04:35:02Z
|    go version :: go1.25.1 linux/amd64

build options:
|    -buildmode :: exe
|     -compiler :: gc
|   CGO_ENABLED :: 1
|    CGO_CFLAGS ::
|  CGO_CPPFLAGS ::
|  CGO_CXXFLAGS ::
|   CGO_LDFLAGS ::
|        GOARCH :: amd64
|          GOOS :: linux
|       GOAMD64 :: v1
|           vcs :: git
|  vcs.revision :: 063bc199778e1ae617c35b70608e4ef104d6ce31
|      vcs.time :: 2025-10-06T04:35:02Z
|  vcs.modified :: false

dependencies:
  h1:iq6aMJDcFYP9uFrLdsiZQ2ZMmcshduyGv4Pek0MQPW0= :: github.com/alecthomas/kong :: v1.12.1
  h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0= :: github.com/joho/godotenv :: v1.5.1
  h1:2CQzrL6rslrsyjqLDwD11bZ5OpLBPU+g3G/r5LSfS8w= :: github.com/lmittmann/tint :: v1.1.2
                                          unknown :: github.com/lrstanley/clix/v2 :: (devel)
                                          unknown :: github.com/lrstanley/x/logging/handlers :: (devel)

You can also use --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 command generate-markdown (hidden when using --help). This will print the markdown to stdout.

./<your-project> generate-markdown > USAGE.md

This functionality is configurable using environment variables:

See example 1 and example 2 for more examples on what this can look like.

Migrating to v2

v2 is an overhaul of the project, changing the underlying parser, logger, and more. The goal is to use more stdlib functionality where possible (like log/slog), making Markdown generation more flexible, and reduce external dependencies. Should be quite a bit less now!

Start by fetching the new version:

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

High-level changes:

• Moved from go-flags to kong. Kong is more maintained, powerful, flexible, and has less issues with parse ordering. Kong is also configured through struct tags, though they are slightly different. Some examples of the naming differences:
  • long -> name
  • description -> help
  • env-delim -> sep
  • required:"true" -> required:""
  • optional:"" for optional commands.
  • command -> cmd
  • See the full list here.
• Kong clears all struct values before parsing, whereas go-flags does not.
• Kong supports pre-validation hooks, resolvers for loading config files, etc.
• Kong doesn't create an env var for flags automatically. In v1, this caused a bunch of bugs, as some auto-created env vars would conflict with commonly used env vars. An example of this being --path, which conflicts with the PATH env var used by most operating systems.
• struct-based flags no longer support --flag foo --flag bar (go-flags style), and now they should be passed in as a single flag, like --flag "foo,bar" with a struct-tag separator defined like sep:"," (the default).
• Version output no longer includes colors, as this required multiple dependencies. I also don't think it added much value.
• Logging, versioning, markdown, and Github runner auto-debug mode are now no longer loaded as plugins when using clix.New, but are still loaded by default when using clix.NewWithDefaults.
• Logging has migrated from github.com/apex/log to log/slog. apex also had pretty bad performance under high load, so you may notice a performance boost.
• Both prettified and JSON logging fields and output look different. JSON logging uses the standard log/slog JSON handler, with source lines added.
• Markdown generation now no longer requires "required" flags to be set, which was quite annoying before. It has moved from --generate-markdown (a flag) to generate-markdown (a command).
• Runner functionality has moved to an external package, github.com/lrstanley/x/scheduler. It now supports crontab-style intervals, and a builder-style interface for creating jobs. See examples/with-scheduler for an example.

See the examples for more details on on what your app should look like.

🙋♂ 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 <liam@liam.sh>

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