Don't include required arguments in usage strings if they can be passed as an env var

[jcgruenhage]

I want to load an access token from an environment variable. It's okay if it can be passed as an arg as well, but seeing it in the usage strings is a bit unsettling, because it encourages passing secrets via CLI args.

I definitely want to load the env var using clap, so that I get the error handling from clap and the variable is included in the generated man page and help.

I've seen #5978, and understand that fully layered config with config files + env vars + cli args is not in the near future. I've also seen #4893, which shows behaviour different from what I'm seeing, but in short it says that having them show up in usage strings is expected and unlikely to change.

Can you expand on why this is the case? I'd like to contribute a PR that changes this behaviour, potentially also in a backwards compatible way that requires people explicitly opt-in to the new behaviour if that helps. But I don't want to invest the time if this is a change that isn't wanted upstream.

[epage]

I definitely want to load the env var using clap, so that I get the error handling from clap and the variable is included in the generated man page and help.

This seems the key part for us to both understand to prepare for talking about the feature.

The generated man and help will be emphasizing the CLI argument, just like the usage, right?

[jcgruenhage]

The generated man page and help will be emphasizing how to use the program, yes. I'll show the help and man page for completeness:

CLI for reserving and (force-)releasing MutexBot resources.

Usage: mutexbot [OPTIONS] --mutexbot-api-key <MUTEXBOT_API_KEY> <COMMAND>

Commands:
  reserve        Reserve a resource
  release        Release a resource
  force-release  Force Release a resource
  help           Print this message or the help of the given subcommand(s)

Options:
      --mutexbot-api-key <MUTEXBOT_API_KEY>
          MutexBot API Key
          
          [env: MUTEXBOT_API_KEY=]

      --isolation-channel <ISOLATION_CHANNEL>
          Isolation channel for resource

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

mutexbot(1)                            General Commands Manual                            mutexbot(1)

NAME
       mutexbot - CLI for reserving and (force-)releasing MutexBot resources

SYNOPSIS
       mutexbot <--mutexbot-api-key> [--isolation-channel] [-h|--help] [-V|--version] <subcommands>

DESCRIPTION
       CLI for reserving and (force-)releasing MutexBot resources.

OPTIONS
       --mutexbot-api-key=MUTEXBOT_API_KEY
              MutexBot API Key
              May also be specified with the MUTEXBOT_API_KEY environment variable.

       --isolation-channel=ISOLATION_CHANNEL
              Isolation channel for resource

       -h, --help
              Print help (see a summary with '-h')

       -V, --version
              Print version

SUBCOMMANDS
       mutexbot-reserve(1)
              Reserve a resource

       mutexbot-release(1)
              Release a resource

       mutexbot-force-release(1)
              Force Release a resource

       mutexbot-help(1)
              Print this message or the help of the given subcommand(s)

VERSION
       v0.2.3

                                            mutexbot 0.2.3                                mutexbot(1)

I think the man page and help both convey in their respective section about options that the API key needs to be provided, either as a CLI arg or as an environment variable. The usage/synopsis strings in both of them put a much stronger emphasis on it being passed as a CLI arg though. Folding it into [OPTIONS] with the remaining options would feel more natural to me, as it is not required as a CLI arg.

[epage]

For me, this is feeling too specialized to have a built-in method for it. This can always be done by manually managing the env variable, including putting it in the help string.

The argument is required one way or the other and the primary way we have to communicate that is the usage line. In addition, the primary way the argument is documented is as an argument and not an environment variable.

Without major other changes, I don't feel like changing the usage line is sufficient enough for this and this feels like a specialized enough of a case. We try to focus on general principles for changing output and common usages to keep the API more discoverable and binary sizes and compile times down. We do have the hide attribute and we could say that that applies to usage also but as a general rule that seems more like a bug than intended for someone to do #[arg(required = true, hide = true)].

[jcgruenhage]

I don't know whether it's too specialized, but I see that this is a niche usecase with a disproportional maintenance burden due to the complexity it introduces. Putting it into the help string and handling it manually works, but it's moving code and documentation apart, which I don't like, but #2763 will resolve that eventually.

Thanks for taking the time to respond :)