Write Useful Messages

It’s never too early to start thinking about the messages you display for your users. Messages include:

• Command summary and description
• Flag summaries and descriptions
• Examples
• Error messages
• Interactive prompts

Two Flags for Different Levels of Help

Because the full help for sf commands can be long, we provide two flags to control how much of the content is displayed:

• --help: Displays all the content.
• -h : Displays a short form of the content Output includes just the command summary, and the USAGE and FLAGS sections. It doesn’t include the long command description, examples, and long flag descriptions.

Implementation Guidelines

Every sf command has a corresponding message file that contains all messages related to that command. Message files live in the top-level messages directory of the plug-in.

Message files use Markdown format and end in .md. Name your file to reflect the corresponding command. For example, the filename for the sf deploy metadata preview is called deploy.metadata.preview.md.

In the Markdown file, each H1 heading is a key that’s referenced in the command's code. The text after the H1 heading is displayed in the --help output.

How to Load Messages

Here's an example of loading messages from the Markdown file hello.world.md in the awesome plugin:

import { Messages } from '@salesforce/core';

Messages.importMessagesDirectory(__dirname);
const messages = Messages.load('awesome', 'hello.world', [
  'summary',
  'description',
  'examples',
  'flags.name.summary',
  'flags.name.description',
]);

The summary, description, and examples keys correspond to help for the command itself. Use the Messages.getMessage() method to reference them in your command class:

  public static readonly summary = messages.getMessage('summary');
  public static readonly description = messages.getMessage('description');
  public static readonly examples = messages.getMessages('examples');

The flags.name.* keys correspond to help for the --name flag. Here's how to reference them in the flag definition:

  public static flags = {
    name: Flags.string({
      char: 'n',
      summary: messages.getMessage('flags.name.summary'),
      description: messages.getMessage('flags.name.description'),
      default: 'World',
    }),
  };

Key Names

Here are the H1 key names we typically use in the core Salesforce CLI command message Markdown files. See the message file for the sf deploy metadata command for an example. See the writing guidelines for tips about writing these messages.

• summary : Required. The short sentence that’s immediately displayed when you run --help or -h.
• description : Optional. Longer command description displayed in the DESCRIPTION help section.
• examples : Required. Displayed in the EXAMPLES help section. Each example must have a brief explanation.
• flags.<flagname>.summary : Required. Short description that’s displayed in the top FLAGS help section.
• flags.<flagname>.description : Optional. Longer flag description displayed in the FLAG DESCRIPTIONS help section.
• error.<errorname> : Required. The error message.
• error.<errorname>.actions : Optional. The suggested action that the user can take to fix the problem.

Displayed Error Messages

The CLI framework automatically prepends the word Error: (or Warning or Info) before the text. For example, if your Markdown file has this:

# error.SandboxNameLength
        
The sandbox name "%s" should be 10 or fewer characters.

At runtime, the resulting error looks like this:

Error: The sandbox name "mysandboxnameisreallylong" should be 10 or fewer characters.

Writing Guidelines

While you're free to write your messages in any style you want, 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 deploy metadata command for an example.

Commands

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

Summary

• Command summaries start with an imperative verb.
  • For example, a good summary for the sf deploy metadata 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.

Description

• Command descriptions are optional but highly encouraged. They are 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? Would 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 need to use quotes to enclose a value when macOS users don’t?
  • Is there another command that the user might confuse with this one? Do you need to 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.

Flags

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

Summary

• Flag summaries are mandatory for each flag. They are displayed in tabular form in the top 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 deploy metadata 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.

Description

• Flag descriptions are optional. They are 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

Examples are the best way to help a user understand what a command does.

• Examples are required. They are displayed in the EXAMPLES section of the --help output. They aren't displayed in the -h output.

• 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:

• If required, provide the context in which the example runs, and the expected outcome. 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, note 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 might 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:

  - Deploy the source files in a directory:
  
    <%= config.bin %> <%= command.id %>  --source-dir path/to/source

Error Messages

Mistakes happen. But on the bright side, they’re opportunities to expand our users' knowledge of the 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 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.