Skip to content

CF CLI Help Guidelines

Jump to bottom
Dies Koper edited this page Aug 16, 2016 · 11 revisions

These guidelines should assist in making cf CLI help messages look consistent and also easy to maintain generated online command reference guide pages from. Help text for new commands, and updates for existing commands should adhere to these guidelines; existing help pages that violate these guidelines will incrementally be updated.

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:

ALIAS:
   c

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

Note:

  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. NAME and USAGE sections are mandatory for each command; all other sections are optional.

  6. Sections are displayed in the order above.

  7. 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).

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

  9. Usage follows the recommendations from http://docopt.org/.

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

  11. Option descriptions are preferably short.

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

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

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

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

Clone this wiki locally