CLI Help template

[ksokolic]

Currently, we are using cobra's automatic output for help. It provides all needed information but not in the most fashionable way.

Inspired by GitHub help we should introduce our own template that provide better usability:

• description
• USAGE
• COMMANDS
• ARGUMENTS
• FLAGS
• EXAMPLES
• GLOBAL FLAGS
• LEARN MORE

Example for mantil aws help

ksenijakordisokolic@Florence Work % mantil aws --help
AWS account subcommand

USAGE
mantil aws [command]

COMMANDS
install       Install Mantil into AWS account.
uninstall     Uninstall Mantil from AWS account.

GLOBAL FLAGS
--help       Show command help.
--no-color   Don't use colors in output.

LEARN MORE
Visit https://docs.mantil.io to learn more.
For further support contact us at [email protected]. 

Example for mantil was install help

ksenijakordisokolic@Florence Work % mantil aws install --help
Install Mantil into AWS account

USAGE
mantil aws install [account-name] [flags]

ARGUMENTS
Argument account-name is for referencing that account in Mantil.
If not provided default name dev will be used for the first account.

FLAGS
--aws-access-key-id string       Access key ID for the AWS account, must be used with the aws-secret-access-key and aws-region flags.
--aws-env                        Use AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION environment variables for AWS authentication.
--aws-profile string             Use the given profile for AWS authentication.
--aws-region string              Region for the AWS account, must be used with and aws-access-key-id and aws-secret-access-key flags.
--aws-secret-access-key string   Secret access key for the AWS account, must be used with the aws-access-key-id and aws-region flags.
--dry-run                        Don't start install/uninstall just show what credentials will be used.
--override                       Force override access tokens on already installed account.

EXAMPLES
You must provide credentials for Mantil to access your AWS account.
There are three ways to provide credentials.

$ mantil aws install --aws-access-key-id=AKIAIOSFODNN7EXAMPLE --aws-secret-access-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY —aws-region=us-east-1
=> Specifies access keys as arguments.

$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_DEFAULT_REGION=us-east-1
$ mantil aws install --aws-env
=> Reads access keys from environment variables. Reference: [https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html).

$ mantil aws install —aws-profile=my-named-profile
=> Uses your named AWS profile from ~/.aws/config. Reference: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

GLOBAL FLAGS
--help       Show command help.
--no-color   Don't use colors in output.

LEARN MORE
Visit https://docs.mantil.io to learn more.
For further support contact us at [email protected]. 

Examples of other help pages and description is available in Notion.

[ianic]

Nesto smo napravili.

[ksokolic]

@djelusic if doable there are few details we should adjust in Help template:

• Change naming FLAGS to OPTIONS
• Change naming AVAILABLE COMMANDS to COMMANDS
• Always start with upper first letter and end with dot (even when explaining options)
• Make links clickable
• Add one space at the end of Help
• Change documentation link to https://help.mantil.com

[djelusic]

Always start with upper first letter and end with dot (even when explaining options)

As discussed we won't end descriptions with a period to stay consistent with the default cobra commands (help and completions). They will also fix some incosistencies in a future release:
spf13/cobra#1458

Make links clickable

This is handled by the terminal, usually if the output contains a well-formed link you can cmd+click it.

Everything else is implemented and will be available in the next release.