CF CLI Help Guidelines

These guidelines should assist in making cf CLI help messages look consistent.

Help text for new commands, and updates for existing commands should adhere to these guidelines; existing help pages that violate these guidelines will be updated incrementally.

Help Page Overview

A command's help page is divided into sections, each with a section title, as follows:

NAME:
   cmd - Command description

USAGE:
   cf cmd ARG1 ARG2 [--option1]

WARNING:
   Providing your password as a command line option is highly discouraged. See also 'cf auth'.
   Your password may be visible to others and may be recorded in your shell history.

EXAMPLE:
   cf login (omit username and password to login interactively -- cf will prompt for both)
   cf login -u name@example.com -p pa55woRD (specify username and password as arguments)
   cf login -u name@example.com -p "my password" (use quotes for passwords with a space)
   cf login -u name@example.com -p "\"password\"" (escape quotes if used in password)
   cf login --sso (cf will provide a url to obtain a one-time password to login)

TIP:
   Value 'none' has been deprecated but is accepted for 'process'.

ALIAS:
   c

OPTIONS:
   -o                      Option's description
   --long-option, -l       Application health check type (e.g. 'port' or 'none')

SEE ALSO:
   some-command, some-other-command

Notes pertaining to all sections:

1. NAME and USAGE sections are mandatory for each command; all other sections are optional. Although in v7 cf CLI, we have been adding SEE ALSO as a helpful section for users.

2. Sections are displayed in the order above.

3. Section titles are localized and are always followed by an ascii colon and a newline: no multibyte colons, nor spaces around the colon (except for in the French locale, which mandates a space before a colon).

4. Text in all sections start with 3 spaces for indentation. No tabs.

5. References to other cf commands in text (e.g. in tips or option descriptions) are enclosed in single quotes and do not include the syntax of the other command.

Section: NAME

1. The help page for all commands start with a NAME section, the command name, space, ascii hyphen, space, followed by a short description of the command.
2. The description starts with a capital letter if common for the locale.
3. The description does not end with a period unless it consists of multiple sentences separated by periods.
4. Ideally the command description is short and consists of only a single sentence.
5. Ideally the command description provides a bit more information than simply repeating the command name in a sentence.
   Compare great example to not so.

Section: USAGE

1. Usage follows the recommendations from http://docopt.org/. It also follows man page conventions of displaying only synopsis, no explanatory text.
   Compare great example to not so.
2. ... is used to signify that an option can be used more than once.

Section: OPTIONS

1. Option descriptions are preferably short.

2. Options with aliases are separated by commas, long option first.

3. The option description starts with a capital letter if common for the locale.

4. The option description does not end with a period unless it consists of multiple sentences separated by periods.

5. Defaults are appended to the option description. E.g. Path on the app (Default: /).

6. Option values referred to in descriptions are enclosed in single quotes.

7. Options are listed in alphabetical (ascii) order.

Section: SEE ALSO

1. This section lists commands a user would like want to refer to/know about when using this command.
   For example, when using create-route, a user may want to know about check-route first to see if the route already exists, and domains to retrieve the possible values for its "DOMAIN" argument, and map-route as the next likely step after creating a route.

2. Commands are displayed as a comma-separated list in alphabetical order.