README
¶
warg
Build heirarchical CLI applications with warg!
- warg uses funcopt style declarative APIs to keep CLIs readable (nested commands can be indented!) and terse. warg does not require code generation.
- warg is extremely interested in getting information into your app. Ensure a flag can be set from an environmental variable, configuration file, or default value by adding a single line to the flag declaration (configuration files also take some app-level config).
- warg is customizable. Add new types of flag values, config file formats, or --help outputs using the public API.
- warg is easy to add to, maintain, and remove from your project (if necessary). This follows mostly from warg being terse and declarative. If you decide to remove warg, simply remove the app declaration and turn the passed flags into other types of function arguments for your command handlers. Done!
Butler Example
In addition to a few examples in the docs, warg includes a small example butler program. See the full source code.
app := warg.New(
"butler",
section.New(
section.HelpShort("A virtual assistant"),
section.Command(
command.Name("present"),
command.HelpShort("Formally present a guest (guests are never introduced, always presented)."),
present,
command.Flag(
flag.Name("--name"),
flag.HelpShort("Guest to address."),
value.String,
flag.Alias("-n"),
flag.EnvVars("BUTLER_PRESENT_NAME", "USER"),
flag.Required(),
),
),
),
)
Run Butler
Color can be toggled on/off/auto with the --color flag:
The default help for a command dynamically includes each flag's current value and how it was was set (passed flag, config, envvar, app default).
Of course, running it with the flag also works
Apps Using Warg
- fling - GNU Stow replacement to manage my dotfiles
- grabbit - Grab images from Reddit
- starghaze - Save GitHub Starred repos to GSheets, Zinc
Should You Use warg?
I'm using warg for my personal projects, but the API is not finalized and there are some known issues (see below). I will eventually improve warg, but I'm currently ( 2021-11-19 ) taking a break from developing on warg to develop some CLIs with warg.
Known Issues
- lists containing aggregate values ( values in list objects from configs ) should be checked to have the same size and source but that must currently be done by the application ( see grabbit )
- Many more types of values need to implemented. Especially StringEnumSlice, StringMap and Duration
Alternatives
- cobra is by far the most popular CLI framework for Go. It relies on codegen.
- cli is also very popular.
- I've used the now unmaintained kingpin fairly successfully.
Concepts
Sections, Commands, and Flags
warg is designed to create heirarchical CLI applications similar to azure-cli (just to be clear, azure-cli is not built with warg, but it was my inspiration for warg). These apps use sections to group subcommands, and pass information via flags, not positional arguments. A few examples:
azure-cli
az keyvault certificate show --name <name> --vault-name <vault-name>
If we try to dissect the parts of this command, we see that it:
- Starts with the app name (
az). - Narrows down intent with a section (
keyvault). Sections are usually nouns and function similarly to a directory heirarchy on a computer - used to group related sections and commands so they're easy to find and use together. - Narrows down intent further with another section (
certificate). - Ends with a command (
show). Commands are usually verbs and specify a single action to take within that section. - Passes information to the command with flags (
--name,--vault-name).
This structure is both readable and scalable. az makes hundreds of commands browsable with this strategy!
grabbit
grabbit is a much smaller app to download wallpapers from Reddit that IS built with warg. It still benefits from the sections/commands/flags structure. Let's organize some of grabbit's components into a tree diagram:
grabbit # app name
├── --color # section flag
├── --config-path # section flag
├── --help # section flag
├── config # section
│ └── edit # command
│ └── --editor # command flag
├── grab # command
│ └── --subreddit-name # command flag
└── version # command
Similar to az, grabbit organizes its capabilities with sections, commands and flags. Sections are used to group commands. Flags defined in a "parent" section are available to child commands. for example, the config edit command has access to the parent --config-path flag, as does the grab command.
Special Flags
TODO
--config
--help + --color
Unsupported CLI Patterns
One of warg's tradeoffs is that it insists on only using sections, commands and flags. This means it is not possible (by design) to build some styles of CLI apps. warg does not support positional arguments. Instead, use a required flag: git clone <url> is spelled git clone --url <url>.
All warg apps must have at least one nested command. 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.
TODO
- make outline help for a command just show the flags
- should I auto add a color flag, what about a version subcommand. I literally want these in all my apps
- Add a sentinal value (UNSET?) to be used with optional flags that unsets the flag? sets the flag to the default value? So I can use fling without passing -i 'README.*' all the time :)
- use https://stackoverflow.com/a/16946478/2958070 for better number handling?
- zsh completion with https://www.dolthub.com/blog/2021-11-15-zsh-completions-with-subcommands/
- go through TODOs in code
- --help ideas: man, json, web, form, term, lsp, bash-completion, zsh-completion, compact
Documentation
¶
Overview ¶
Declaratively create heirarchical command line apps.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// HelpFile contains the file set in OverrideHelpFlag.
// HelpFile is part of the public API to allow for easier testing.
// HelpFile is never closed by warg, so if setting it to something other than stderr/stdout,
// please remember to close HelpFile after using ParseResult.Action (which writes to HelpFile).
HelpFile *os.File
// contains filtered or unexported fields
}
An App contains your defined sections, commands, and flags Create a new App with New()
func New ¶
New builds a new App!
Example ¶
package main
import (
"fmt"
"os"
"go.bbkane.com/warg"
"go.bbkane.com/warg/command"
"go.bbkane.com/warg/flag"
"go.bbkane.com/warg/section"
"go.bbkane.com/warg/value"
)
func login(pf flag.PassedFlags) error {
url := pf["--url"].(string)
// timeout doesn't have a default value,
// so we can't rely on it being passed.
timeout, exists := pf["--timeout"]
if exists {
timeout := timeout.(int)
fmt.Printf("Logging into %s with timeout %d\n", url, timeout)
return nil
}
fmt.Printf("Logging into %s\n", url)
return nil
}
func main() {
app := warg.New(
section.New(
"work with a fictional blog platform",
section.Command(
"login",
"Login to the platform",
login,
),
section.Flag(
"--timeout",
"Optional timeout. Defaults to no timeout",
value.Int,
),
section.Flag(
"--url",
"URL of the blog",
value.String,
flag.Default("https://www.myblog.com"),
flag.EnvVars("BLOG_URL"),
),
section.Section(
"comments",
"Deal with comments",
section.Command(
"list",
"List all comments",
// still prototyping how we want this
// command to look,
// so use a provided stub action
command.DoNothing,
),
),
),
)
// normally we would rely on the user to set the environment variable,
// bu this is an example
err := os.Setenv("BLOG_URL", "https://envvar.com")
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
app.MustRun([]string{"blog.exe", "login"}, os.LookupEnv)
}
Output: Logging into https://envvar.com
func (*App) MustRun ¶
func (app *App) MustRun(osArgs []string, osLookupEnv LookupFunc)
MustRun runs the app. Any flag parsing errors will be printed to stderr and os.Exit(64) (EX_USAGE) will be called. Any errors on an Action will be printed to stderr and os.Exit(1) will be called.
func (*App) Parse ¶
func (app *App) Parse(osArgs []string, osLookupEnv LookupFunc) (*ParseResult, error)
Parse parses the args, but does not execute anything.
type AppOpt ¶
type AppOpt func(*App)
AppOpt let's you customize the app. Most AppOpts panic if incorrectly called
func ConfigFlag ¶
func ConfigFlag( configFlagName flag.Name, newConfigReader config.NewReader, helpShort flag.HelpShort, flagOpts ...flag.FlagOpt, ) AppOpt
Use ConfigFlag in conjunction with flag.ConfigPath to allow users to override flag defaults with values from a config.
Example ¶
package main
import (
"fmt"
"io/ioutil"
"log"
"os"
"go.bbkane.com/warg"
"go.bbkane.com/warg/command"
"go.bbkane.com/warg/config/yamlreader"
"go.bbkane.com/warg/flag"
"go.bbkane.com/warg/section"
"go.bbkane.com/warg/value"
)
func exampleConfigFlagTextAdd(pf flag.PassedFlags) error {
addends := pf["--addend"].([]int)
sum := 0
for _, a := range addends {
sum += a
}
fmt.Printf("Sum: %d\n", sum)
return nil
}
func main() {
app := warg.New(
section.New(
"do math",
section.Command(
command.Name("add"),
"add integers",
exampleConfigFlagTextAdd,
command.Flag(
flag.Name("--addend"),
"Integer to add. Floats will be truncated. Flag is repeatible",
value.IntSlice,
flag.ConfigPath("add.addends"),
flag.Required(),
),
),
),
warg.ConfigFlag(
"--config",
yamlreader.New,
"path to YAML config file",
flag.Alias("-c"),
flag.Default("~/.config/calc.yaml"),
),
)
err := ioutil.WriteFile(
"testdata/ExampleConfigFlag/calc.yaml",
[]byte(
`
add:
addends:
- 1
- 2
- 3
`),
0644,
)
if err != nil {
log.Fatalf("write error: %e", err)
}
app.MustRun([]string{"calc", "-c", "testdata/ExampleConfigFlag/calc.yaml", "add"}, os.LookupEnv)
}
Output: Sum: 6
func Name ¶ added in v0.0.13
Name sets the app name. If not passed, the first value in the list passed to Parse will be used. Usually, the value passed to Parse is os.Args, so os.Args[0] ends up as the name
func OverrideHelpFlag ¶
func OverrideHelpFlag( mappings []help.HelpFlagMapping, helpFile *os.File, flagName flag.Name, flagHelp flag.HelpShort, flagOpts ...flag.FlagOpt, ) AppOpt
OverrideHelpFlag customizes your --help. If you write a custom --help function, you'll want to add it to your app here!
Example ¶
package main
import (
"fmt"
"os"
"go.bbkane.com/warg"
"go.bbkane.com/warg/command"
"go.bbkane.com/warg/flag"
"go.bbkane.com/warg/help"
"go.bbkane.com/warg/section"
)
func exampleOverrideHelpFlaglogin(pf flag.PassedFlags) error {
fmt.Println("Logging in")
return nil
}
func exampleOverrideHelpFlagCustomCommandHelp(file *os.File, _ *command.Command, _ help.HelpInfo) command.Action {
return func(_ flag.PassedFlags) error {
fmt.Fprintln(file, "Custom command help")
return nil
}
}
func exampleOverrideHelpFlagCustomSectionHelp(file *os.File, _ *section.SectionT, _ help.HelpInfo) command.Action {
return func(_ flag.PassedFlags) error {
fmt.Fprintln(file, "Custom section help")
return nil
}
}
func main() {
app := warg.New(
section.New(
"work with a fictional blog platform",
section.Command(
"login",
"Login to the platform",
exampleOverrideHelpFlaglogin,
),
),
warg.OverrideHelpFlag(
[]help.HelpFlagMapping{
{
Name: "default",
CommandHelp: help.DetailedCommandHelp,
SectionHelp: help.DetailedSectionHelp,
},
{
Name: "custom",
CommandHelp: exampleOverrideHelpFlagCustomCommandHelp,
SectionHelp: exampleOverrideHelpFlagCustomSectionHelp,
},
},
os.Stdout,
"--help",
"Print help",
flag.Alias("-h"),
// the flag default should match a name in the HelpFlagMapping
flag.Default("default"),
),
)
app.MustRun([]string{"blog.exe", "-h", "custom"}, os.LookupEnv)
}
Output: Custom section help
func SkipValidation ¶ added in v0.0.13
func SkipValidation() AppOpt
SkipValidation skips (most of) the app's internal consistency checks when the app is created. If used, make sure to call app.Validate() in a test!
type LookupFunc ¶
Look up keys (meant for environment variable parsing) - fulfillable with os.LookupEnv or warg.LookupMap(map)
func LookupMap ¶
func LookupMap(m map[string]string) LookupFunc
LookupMap loooks up keys from a provided map. Useful to mock os.LookupEnv when parsing
type ParseResult ¶
type ParseResult struct {
// Path to the command invoked. Does not include executable name (os.Args[0])
Path []string
// PassedFlags holds the set flags!
PassedFlags flag.PassedFlags
// Action holds the passed command's action to execute.
Action command.Action
}
ParseResult holds the result of parsing the command line.
Source Files
Directories