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.

How to Load Messages

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

1import { Messages } from "@salesforce/core";
2
3Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
4const messages = Messages.loadMessages("awesome", "hello.world");

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

1public static readonly summary = messages.getMessage('summary');
2  public static readonly description = messages.getMessage('description');
3  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:

1public static readonly flags = {
2    name: Flags.string({
3      char: 'n',
4      summary: messages.getMessage('flags.name.summary'),
5      description: messages.getMessage('flags.name.description'),
6      default: 'World',
7    }),
8  };

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

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:

1# error.SandboxNameLength
2
3The 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.

Flag Groups

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:

1public static readonly flags = {
2  ...
3      'no-namespace': Flags.boolean({
4      char: 'm',
5      summary: messages.getMessage('flags.no-namespace.summary'),
6      helpGroup: 'Packaging',
7    }),

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

Topic Messages

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:

1$ sf data --help
2Manage records in your org.
3
4USAGE
5  $ sf data COMMAND
6
7TOPICS
8  data bulk    Get the results of a bulk ingest job that you previously ran.
9  data create  Create a record or a file.
10  data delete  Delete a single record or multiple records in bulk.
11  data export  Export data from your org.
12  data get     Get a single record.
13  data import  Import data to your org.
14  data update  Update many records.
15  data upsert  Upsert many records.
16
17COMMANDS
18  data query   Execute a SOQL query.
19  data resume  View the status of a bulk data load job or batch.
20  data search  Execute a SOSL text-based search query.

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:

1"data": {
2        "description": "Manage records in your org.",
3        "subtopics": {
4          "create": {
5            "description": "Create a record or a file."
6          },
7          "delete": {
8            "description": "Delete a single record or multiple records in bulk."
9          },
10          "export": {
11            "description": "Export data from your org.",
12            "external": true
13          },
14          "get": {
15            "description": "Get a single record."
16          },
17          "import": {
18            "description": "Import data to your org.",
19            "external": true
20          },
21          "query": {
22            "description": "Query records."
23          },
24          "update": {
25            "description": "Update many records.",
26            "external": true
27          },
28          "upsert": {
29            "description": "Upsert many records."
30          }
31        },
32        "external": true
33      }