kongusage

README

kongusage

Usage

Add a hidden flag to the Kong CLI struct:

type CLI struct {
    // ...
    UsageSpec kongusage.Flag `hidden:"" help:"Print usage spec (KDL) of this CLI."`
}

Then the program prints its usage spec in KDL by --usage-spec.

Example: shell completion

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" --install

Replace 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.

Example: completion of a mise task

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.

Documentation

Overview

Package kongusage adds [usage](https://usage.jdx.dev/) spec support for Kong CLI.

Index

• type Flag
  • func (Flag) BeforeReset(app *kong.Kong) error

Types

type Flag

type Flag bool

Flag prints the usage spec of the CLI in KDL and exits, like kong.VersionFlag.

Declare it as a field with the tag `hidden:""`, so it doesn't clutter the help. The name of the flag comes from the name of the field (e.g. field UsageSpec gives flag --usage-spec).

func (Flag) BeforeReset

func (Flag) BeforeReset(app *kong.Kong) error

BeforeReset implements the Kong hook.