Message 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 project convert source is called convert.source.md.

In the Markdown file, each H1 heading is a key that’s referenced in the command's code. Most commands always have the summary, description, and examples keys. The text after the key's H1 heading is displayed in the --help output.

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

Use the messages.getMessage() or messages.getMessages() methods to reference the H1 keys from the markdown file in your command class:

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

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 project deploy start 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 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.

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

At runtime, the resulting error looks like this:

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

If your command has many flags, you can group them in the --help output to make it easier to find a particular flag.

How many is too many? That's up to you. Run sf org create scratch to see an example. The help output includes the standard FLAGS and GLOBAL FLAGS groups and the command-specific PACKAGING FLAGS and DEFINITION FILE OVERRIDE FLAGS groups.

To implement a flag group, use the helpGroup flag property. This example shows how to add the --no-namespace flag of org create scratch to a group called PACKAGING FLAGS:

In the actual --help output, the help group Packaging is rendered as PACKAGING FLAGS.

A topic is a collection or “bucket” of commands within Salesforce CLI. When you use the --help flag on a topic, the output includes the topic summary, a list of sub-topics, and the commands contained in the topic. Here's sample help output for the data topic:

Write topic summaries in the package.json file in the top-level directory of your plugin. Topic summaries aren't in the Markdown files in the messages directory like other help messages. In the package.json file, topic summaries live in the topics sub-object of the oclif object and are defined with a description property. Here's a snippet of the package.json file of the plugin-data plugin which specifies the topic summary of the data topic and its subtopics: