Skip to content

Navigation Menu

Sign in
Sign up

Latest commit

History

481 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

warg

An opinionated CLI framework:

  • declarative nested commands
  • detailed, colored --help output (including what a flag is currently set to)
  • update flags from os.Args, config files, environment variables, and app defaults
  • extend with new flag types, config file formats, or --help output
  • snapshot testing support

Project Status (2025年06月15日)

warg is still a work in progress, but the "bones" are where I want them - I don't intend to change the basic way warg works, but I do plan to experiment with a few APIs (make the value and config APIs simpler), and add TUI generation. I think the largest breaking changes are behind me (see the CHANGELOG). Read Go Project Notes to help understand the tooling.

I'm watching issues; please open one for any questions and especially BEFORE submitting a Pull request.

Examples

All of the CLIs on my profile use warg.

See API docs (including code examples) at pkg.go.dev

Simple "butler" example (full source here):

app := warg.New(
 "butler",
 "v1.0.0",
 warg.NewSection(
 "A virtual assistant",
 warg.NewSubCmd(
 "present",
 "Formally present a guest (guests are never introduced, always presented).",
 present,
 warg.NewCmdFlag(
 "--name",
 "Guest to address.",
 scalar.String(),
 warg.Alias("-n"),
 warg.EnvVars("BUTLER_PRESENT_NAME", "USER"),
 warg.Required(),
 ),
 ),
 ),
)

Butler help screenshot

When to avoid warg

By design, warg apps have the following requirements:

  • must contain at least one subcommand. This makes it easy to add further subcommands, such as a version subcommand. It is not possible to design a warg app such that calling <appname> --flag <value> does useful work. Instead, <appname> <command> --flag <value> must be used.
  • warg does not support positional arguments. Instead, use a required flag: git clone <url> would be git clone --url <url>. This makes parsing much easier, and I like the simplicity of it, even though it's more to type/tab-complete.

Alternatives

  • cobra is by far the most popular CLI framework for Go.
  • cli is also very popular.
  • I haven't tried ff, but it looks similar to warg, though less batteries-included
  • I've used the now unmaintained kingpin fairly successfully. They also wrote a successor framework named kong
  • go-arg looks quite clean too

Notes

See Go Project Notes for notes on development tooling.

About

Declarative CLI framework

Topics

Resources

Stars

56 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages

AltStyle によって変換されたページ (->オリジナル) /