---
schema_version: "1"
id: 33c272ebf2f60239ad4a27ed2a0a041c2b49b651103e38225daa0cab618c327f
title: Message Implementation Guidelines
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/salesforcedx/sfcliplugin/guides/messages/messages-impl-guidelines.md
canonical_url: https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/guide/messages-impl-guidelines.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: b44bd22e44a3de299966b0a89bd3a4ef45c1d8b53b6edcbb7292fdb2a55be2e9
products:
  - Salesforce CLI Plugin Developer Guide
  - salesforcedx
---
# 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](https://github.com/salesforcecli/plugin-deploy-retrieve/tree/main/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:

```typescript
import { Messages } from "@salesforce/core";

Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
const 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:

```typescript
  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:

```typescript
  public static readonly 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](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/main/messages/deploy.metadata.md) for the `sf project deploy start` command for an example. See the [writing guidelines](https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/guide/messages-writing-guidelines.md) 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:

```markdown
# 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.`

## 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](https://github.com/salesforcecli/plugin-org/blob/main/src/commands/org/create/scratch.ts#L91) shows how to add the `--no-namespace` flag of `org create scratch` to a group called PACKAGING FLAGS:

```typescript
  public static readonly flags = {
  ...
      'no-namespace': Flags.boolean({
      char: 'm',
      summary: messages.getMessage('flags.no-namespace.summary'),
      helpGroup: 'Packaging',
    }),
```

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

## Topic Messages

A [topic](https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/design/topics.md) 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:

```bash
$ sf data --help
Manage records in your org.

USAGE
  $ sf data COMMAND

TOPICS
  data bulk    Get the results of a bulk ingest job that you previously ran.
  data create  Create a record or a file.
  data delete  Delete a single record or multiple records in bulk.
  data export  Export data from your org.
  data get     Get a single record.
  data import  Import data to your org.
  data update  Update many records.
  data upsert  Upsert many records.

COMMANDS
  data query   Execute a SOQL query.
  data resume  View the status of a bulk data load job or batch.
  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](https://github.com/salesforcecli/plugin-data/blob/main/package.json) which specifies the topic summary of the `data` topic and its subtopics:

```json
      "data": {
        "description": "Manage records in your org.",
        "subtopics": {
          "create": {
            "description": "Create a record or a file."
          },
          "delete": {
            "description": "Delete a single record or multiple records in bulk."
          },
          "export": {
            "description": "Export data from your org.",
            "external": true
          },
          "get": {
            "description": "Get a single record."
          },
          "import": {
            "description": "Import data to your org.",
            "external": true
          },
          "query": {
            "description": "Query records."
          },
          "update": {
            "description": "Update many records.",
            "external": true
          },
          "upsert": {
            "description": "Upsert many records."
          }
        },
        "external": true
      }
```