Improve documentation for the CLI spec

[roman]

For the input value, use something similar to this example:

With my-app --foo the --foo is an input of type switch (from what I gather, it does not have a value associated to the flag), and it translates to a Boolean in the end (was --foo specified?)

With my-app --foo bar the --foo is an input of type option

With my-app bar, the input is of type argument as it is a positional argument

I think there is a limitation in regards on how the positional arguments order is decided (right now it could be rather arbitrary)

For the metavar, use something similar to this:

The metavar value is to change the name of an input in the --help message, when you do a --help and you have a command with option --option that has a metavar with METAVAR_VALUE_IS_THIS it will display a message somewhat like:

program header - some header description

--option METAVAR_VALUE_IS_THIS