Environment variables

[jethron]

Cool initiative!

I think it would be useful if an OpenCLI doc could detail environment variables the program observes, the expected values, descriptions of how they change behaviour, etc.

Bonus points if there were a way to "map" them to their equivalent arguments/options when applicable, although that might be a bit more challenging to represent cleanly in a JSON document without more complex concepts like JSON Pointers. So perhaps that is best left to the existing metadata.

[patriksvensson]

@jethron Yes, I think that is an excellent idea! How do you imagine that it should be expressed in the specification?

[cmcgee1024]

Here's an idea of how environment variables can be integrated into the specification, written as a draft PR: #47

The idea is that environment variables can be declared for a tool in two places. First is at the top-level where every variable that the tool uses is declared there. Since variables can be generally accessed from anywhere and have different effects this global declaration can serve as the default place to declare their usage. Plus, it allows documentation generators to easily summarize them in the absence of a particular subcommand that might be of interest to the reader. It can be the case that environment variables could be scoped to only certain subcommands, and perhaps that would be an argument to include environment variables at the command-level too.

The second place for the environment variables is options where the default value is set to the value of an environment variable. Declaring this relationship helps to reason about the defaults for certain options. Providing a value to an option overrides the value to a specific environment variable, which limits its effect in certain invocations, and so it's good to be aware of the override. Also, the naming of the option and environment variable cannot usually be inferred because options occur in a constrained namespace, and variables exist in a global namespace requiring extra qualifiers to avoid collision.

Much like options and arguments, I expect that environment variables will benefit from additional metadata, such as its type (string, integer, enumeration), and also whether it is a file path (directory, file, input, output).