kongusage generates a usage spec
of a CLI built with Kong.
With the spec, the usage CLI provides shell completion of the program
for bash, zsh, fish, nu and PowerShell,
mise completes arguments of tasks which run it,
and usage generates docs and checks compatibility between releases.
A flag added to the CLI is enough to print the spec;
features which Kong lacks, like examples or completion of values by a command,
are added to it in KDL.
Add a flag to the Kong CLI struct:
type CLI struct {
kongusage.UsageSpec
// ...
}With kong.DefaultEnvars declare the flag as a field with the tag env:"-" instead:
only the command line sets it, so help should not show a variable for it.
type CLI struct {
UsageSpec kongusage.Flag `env:"-"`
// ...
}Then the program prints its usage spec in KDL by --usage-spec.
The flag alone is enough to generate a spec, but the spec includes only what Kong knows.
Features of usage which Kong has no counterpart for,
e.g. examples, long help, notes or completion of values,
are given in KDL by the method UsageKDL() of the root, command, flag and positional types
and by the tag usage-kdl of their fields:
type CLI struct {
kongusage.UsageSpec
Force bool `help:"Overwrite files." usage-kdl:"effect=destructive"`
Deploy DeployCmd `cmd:"" help:"Deploy the release."`
Hosts HostsCmd `cmd:"" help:"Print known hosts, one per line." hidden:""`
}
func (CLI) UsageKDL() string {
return `
license MIT
cmd "deploy" {
example "my-kong-cli deploy --env=prod web1" header="Deploy to production"
flag "--env <ENV>" { note "Deploying to prod needs approval." }
}
`
}
type DeployCmd struct {
Env string `placeholder:"ENV" enum:"prod,dev" default:"dev" help:"Environment."`
Host Host `arg:"" help:"Host to deploy to."`
}
type Host string
func (Host) UsageKDL() string {
return `arg "" { complete run="my-kong-cli hosts" }`
}The package doc
explains the sources and where to put which feature;
docs/usage-features.md lists the accepted nodes
and how they are merged.
When a hook or the tag changes the node given by UsageKDL(), mind that:
long_helpandhelp_mdare different nodes, so one does not replace the other; the same holds forbefore_helpandbefore_help_md,after_helpandafter_help_md.noteandwarningare different nodes too.- One
exampleof the tag replaces all examples given byUsageKDL(), and so donote,warning,exit_codeandoutput. completeis replaced as a whole, e.g.complete type=filedropsrunof the old one.
Features which would repeat on many commands, flags or positional arguments
can be given by the hooks Config.NodeKDL and Config.ValueKDL:
a hook returns a string in the same format as the tag for each of them,
and it is merged the same way, before the tag of the field.
Add a test which checks the spec, and install the usage CLI where tests run (the test fails without it and names the version to install):
func TestUsageSpec(t *testing.T) {
kongusage.CheckSpec(t, kong.Must(&CLI{}))
}The test is required for a CLI with usage-only features:
--usage-spec panics on a mistake in them, and CheckSpec finds it.
We recommend it for any CLI, as it also reports errors and warnings of usage lint
and logs each part of the CLI which the spec fixes silently,
e.g. a placeholder which usage cannot take as a value name;
but a CLI which only adds the flag can do without it.
Set KONGUSAGE_TEST_SKIP_USAGE=1 where usage is not available (e.g. some CI platforms):
then the test does not run usage and checks only usage-only features.
docs/mapping.md describes how Kong maps to the spec and which Kong features are lost.
The usage CLI generates a completion script which reads the spec from the installed program:
usage generate completion zsh my-kong-cli --usage-cmd "my-kong-cli --usage-spec" --installReplace zsh by bash, fish, nu or powershell for another shell.
The script runs usage and my-kong-cli --usage-spec on each Tab,
so completion always matches the installed version of the program,
and usage must be in $PATH wherever the script is used.
A mise task which runs the program can take the spec for completion:
[tasks.my-kong-cli]
usage = 'mount run="mise run -q my-kong-cli --usage-spec"'
raw_args = true # Kong parses arguments, usage is only for completion.
run = 'my-kong-cli'mise runs the mount command only to complete arguments of the task,
so the spec is never stale.
raw_args = true makes mise pass arguments to run as is instead of parsing them by the spec,
so --help and invalid flags reach Kong.
An alternative takes the spec from a file generated by my-kong-cli --usage-spec,
so mise tasks info and mise generate task-docs show it too:
[tasks.my-kong-cli]
usage = 'include file="{{ config_root }}/my-kong-cli.usage.kdl"'
raw_args = true
run = 'my-kong-cli'The file must be regenerated whenever the program changes. A missing or broken file makes the task fail and silently breaks completion of every task of the project (jdx/mise#15462).
Completed paths are relative to the shell's directory,
while the task runs in its dir, by default the mise config root directory,
so a relative path completed in another directory is wrong for the program.
A program which takes paths from the user as a task has to resolve them
relative to MISE_ORIGINAL_CWD when it is set,
unless the task runs in the shell's directory (dir = '{{cwd}}')
or the user runs the task only from the mise config root directory.
usage diff reports breaking changes of the command line
since the released version, and exits 1 when there are any:
my-kong-cli --usage-spec | usage diff released.usage.kdl -A new version of kongusage may change the spec of an unchanged CLI, which is reported as a change too.
- kong-usage
also generates a usage spec of a Kong CLI.
It is a minimal solution, enough for simple CLIs:
it maps commands, flags and positional arguments with their basic properties.
A few mappings its README lists are not emitted (
version,subcommand_required), and flags of a command are not completed after its subcommand.
kongusage (this project) aims to be a complete one:
it describes as much of the behaviour of Kong as usage can express
(e.g. flag groups, default commands, inherited flags, completion of values by their type),
documents what is lost, takes usage-only features from the author of the CLI,
and checks the spec by usage lint in a test.
Shell completion of a Kong CLI without usage, which neither the usage CLI nor mise tasks can use:
- kongplete: completion by posener/complete.
- kong-completion: completion for bash, zsh, fish.