Skip to content

Add Context.showEnvvarsInHelp to show envvar names in help output#641

Open
gildor wants to merge 1 commit into
ajalt:masterfrom
gildor:envvar-help-tag
Open

Add Context.showEnvvarsInHelp to show envvar names in help output#641
gildor wants to merge 1 commit into
ajalt:masterfrom
gildor:envvar-help-tag

Conversation

@gildor

@gildor gildor commented Jun 5, 2026

Copy link
Copy Markdown

Adds an opt-in way to show the name of the environment variable that an option reads its value from in the --help output:

class Tool : CliktCommand() {
    init {
        context {
            autoEnvvarPrefix = "TOOL"
            showEnvvarsInHelp = true
        }
    }
    val explicit by option(help = "explicit envvar name", envvar = "MY_OPTION")
    val inferred by option(help = "inferred envvar name")
}
Options:
  --explicit=<text>  explicit envvar name (env var: MY_OPTION)
  --inferred=<text>  inferred envvar name (env var: TOOL_INFERRED)
  -h, --help         Show this message and exit

Both explicit envvar names and names inferred from autoEnvvarPrefix are shown. Eager options (like --help and --version) never read envvars, so they never get the tag.

The tag is computed in Option.parameterHelp(context) - the only place with access to both the option's envvar and the context's autoEnvvarPrefix — and flows through the existing help tag pipeline, so no formatter changes were needed beyond localizing the new HelpFormatter.Tags.ENVVAR tag. It renders identically in MordantHelpFormatter, PlaintextHelpFormatter, and the markdown formatter.

That also means all the existing customization hooks apply to it for free:

  • label text: Localization.helpTagEnvvar() (defaults to "env var")
  • format/visibility: the open renderTag / shouldShowTag formatter methods
  • styling: styleHelpTag (theme.style("muted")), same as the other tags

Per-option override

Individual options can override the global setting through their existing helpTags parameter:

// hide the envvar name for one option while showEnvvarsInHelp is on:
val secret by option(envvar = "TOOL_SECRET", helpTags = mapOf(HelpFormatter.Tags.ENVVAR to ""))

// or show it for one option while the setting is off:
val opt by option(envvar = "TOOL_OPT", helpTags = mapOf(HelpFormatter.Tags.ENVVAR to "TOOL_OPT"))

Default

The setting is off by default, so existing help output is byte-identical. Since envvar support is invisible to users without this (see request in #320), probably it is worth enabling it by default in a future release - happy to follow whatever you prefer here.

Closes #320

Add an opt-in context setting that shows the name of the environment
variable an option reads its value from in the help output, rendered
through the existing help tag pipeline as "(env var: FOO)". Both
explicit envvar names and names inferred from autoEnvvarPrefix are
shown. Since the setting is on the context, it propagates to
subcommands.

Individual options can override the displayed name (or hide it) by
setting the new HelpFormatter.Tags.ENVVAR key in their helpTags. The
tag text is localizable via Localization.helpTagEnvvar, and rendering
is customizable through the existing renderTag/shouldShowTag/
styleHelpTag formatter hooks, same as the default and required tags.

References ajalt#320
@gildor
gildor force-pushed the envvar-help-tag branch from 18519ac to f9562b9 Compare June 5, 2026 02:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support printing environment variables in --help

1 participant