Writing Guidelines

You can write your messages in any style you want, but we recommend that you follow these guidelines so that your commands feel similar to the core Salesforce CLI commands. See the message file for the sf project deploy start command for an example.

Use clear, concise descriptions so that users can easily and quickly understand what your commands do.

  • Command summaries start with an imperative verb.
    • For example, a good summary for the sf project deploy start command is Deploy metadata to an org from your local project.
  • Summaries are mandatory for each command.
  • The summary is the first message that displays when users run --help or -h for a specific command. The summary is also displayed as the first sentence in the DESCRIPTION section when using --help. It's also the message that’s displayed when using --help to list a group of commands.
  • Summaries include just enough information to tell users what the command helps them do, but are as short as possible.
  • Summaries use proper punctuation and capitalization and are complete sentences.
  • In the Markdown file, put the entire command summary in a single line. If the summary contains a newline, only the first line is printed in the --help.
  • Command descriptions are optional but highly encouraged. They're displayed in the --help output, but not the -h output.
  • Write them to expand on the summary, provide context about how and when a user runs the command, describe the behavior of the command, and provide other helpful information for the user. Here are some questions to help you pinpoint this other helpful information; not all questions are relevant to all commands.
    • Where does this command fit in a typical developer workflow? Does it help the user to know which commands are typically run before or after?
    • What, if any, are the repercussions of using this command? Is the command destructive? For example, does the command overwrite files in an org? Overwrite local files?
    • Does the command behave unexpectedly when a user specifies a particular combination of flags?
    • Is the command output easy to read, or is it complex enough that you should describe how to interpret it?
    • Is there an operating system-specific gotcha? For example, do Windows users use quotes to enclose a value but macOS users don’t?
    • Is there another command that the user can confuse with this one? Should you describe the use cases for each command?
  • While there’s no theoretical limit to the length of a long description, try to keep it brief yet comprehensive.
  • Long descriptions use proper punctuation and capitalization and are complete sentences.

Use clear, concise descriptions so that users can easily understand what the command flags do.

  • Flag summaries are mandatory for each flag. They're displayed in tabular form in the FLAGS section of both the --help and -h output.
  • Flag summaries include just enough information to tell users what the flag does, but are as short as possible to minimize wrapping in narrow terminals.
  • For flags that accept a value, the summary describes the value that the user supplies.
    • For example, a good summary for the --manifest flag of the sf project deploy start command is Full file path for manifest (package.xml) of components to deploy.
  • For flags of type Boolean, which alter the behavior of a command but don't accept a value, the summary tells users what the flag makes the command do. Start these descriptions with an imperative verb.
    • For example, the summary for the global --json flag is Format output as json.
  • Flag summaries use proper punctuation and capitalization and are complete sentences.
  • In the Markdown file, put the entire command summary in a single line. If the summary contains a newline, only the first line is printed in the --help.
  • Flag properties that are defined in the command's source code, such as whether the flag is required or its default value, are automatically displayed in the --help. Don't duplicate this information in the flag summary or description.
  • Flag descriptions are optional. They're displayed in the FLAG DESCRIPTIONS section of the --help output. They aren't displayed in the -h output.
  • Write flag descriptions to expand on the summary, provide context and other helpful information for the user.
  • Don’t duplicate information in flag descriptions that’s in your command description.
  • Flag descriptions use proper punctuation and capitalization and are complete sentences.
  • There’s no limit to the length of a flag description, but remember that short is sweet.

Examples are the best way to help a user understand what a command does. Examples are displayed in the EXAMPLES section of the --help output. They aren't displayed in the -h output.

  • You must include at least one example.

  • For each example, provide a brief explanation. Start with an imperative and end with a colon. For example:

    • Deploy the source files in a directory:

  • Use long flag names (--definition-file) in the examples, not short names (-f). Long names make the example more clear.

  • Show an example of using each required flag; you can show multiple required flags in a single example, if it makes "real world" sense.

  • If necessary, provide the context in which the example runs, and the expected effect. Don’t show the actual output, just a brief description of what it should be. But be judicious and brief.

  • If you provide multiple examples, explain how they differ and when to use one over another.

  • Don’t duplicate information in examples that’s already in your command and flag descriptions.

  • If necessary, provide any prerequisites to help users run their own examples. Warn users of any “gotchas” they can encounter. But again, be judicious and brief.

  • To keep the examples operating-system agnostic, use <%= config.bin %> <%= command.id %> instead of sf your-command. The CLI converts this string to the appropriate OS prompt and command name at runtime. See this example.

  • For correct formatting in the --help output, precede the explanation in the Markdown file with "-" and the example itself with two spaces. For example:

Mistakes happen. But on the bright side, they’re opportunities to expand our users' knowledge of Salesforce CLI by providing them an excellent error message.

  • Use an error message to tell users how to recover from the situation that caused the error.
  • Before writing an error message, find out whether the command design can be changed to avoid the error.
  • Tell users concisely, but also completely, what went wrong and what they can do about it. For example:
    • Error message: This command doesn't accept an access token for a username.
    • Action (aka “Try this:”): Specify a username or an alias.
  • Two short sentences are usually better than one long one. However, rather than first stating the problem and then the solution you can sometimes easily imply the problem in the solution. When possible, say what users can do instead of what they can’t.
  • A good error message helps users move on rather than making them feel bad.
  • Error messages use proper punctuation and capitalization and are complete sentences.