cliflags

README

docs

Documentation

Overview

Package cliflags provides a go/analysis analyzer enforcing the flag shape of the opinionated CLI standard on every urfave/cli v3 flag literal. Each rule is one line of the go-cli standard:

• every flag binds an environment variable via Sources: cli.EnvVars(...)
• every flag whose zero value is not its sensible default carries an explicit default via Value. A boolean's false and a container's empty ARE that default, so bool, slice and map flags carry none; every other value type v3 ships has a zero that is a value rather than an emptiness
• flag names are kebab-case, the empty name included: it names no flag
• an app-specific environment variable is UPPERCASE_SNAKE_CASE (prefixed with the app name when -app is set), while a well-known external variable (PG*, AWS_*, DOCKER_*, ...) is used UNPREFIXED — no KILROY_PGHOST; libpq already owns PGHOST
• no flag is Required — a required flag is a positional argument in disguise

A flag literal is a single-package fact, which is what makes these rules analyzer-shaped; the surrounding package structure is yze/cliapp's and stickler/clilayout's business. The well-known namespace list is seeded from the standard's own examples and extended with -external, whose entries are trimmed and validated when the setting is applied — a namespace that cannot name an environment variable is refused rather than registered.

One exemption inverts a rule: a flag literal a file installs in one of the framework's own package-level Flag variables (cli.VersionFlag, cli.HelpFlag, cli.GenerateShellCompletionFlag) is forbidden Sources instead of required to have them, because v3 reads those before Sources apply.

Index

• Constants
• Variables

Constants

const ErrExternalNamespace errs.Const = "-external entry is not an environment-variable namespace"

ErrExternalNamespace reports an -external entry that cannot name an environment variable, so registering it would narrow nothing. go-yze's ApplyConfig turns a Set error into goyze.ErrInvalidSettingValue, and a standalone run fails flag parsing, so the operator is told rather than left believing a rule is narrowed.

Variables

var Analyzer = newAnalyzer()

Analyzer reports urfave/cli v3 flag literals that break the flag standard.

var Registration = goyze.Registration{
	Precision:  goyze.PrecisionJudgment,
	Name:       "cliflags",
	Categories: []goyze.Category{"cli"},
	URL:        "https://docs.gomatic.dev/yze/cliflags",
	Analyzer:   Analyzer,
}

Registration declares this analyzer to the yze framework.