Conceptual Overview of Salesforce CLI

What Is a Salesforce CLI Plugin?

A Salesforce plugin is a set of commands that are grouped together. For example, the plugin-deploy-retrieve plugin provides commands to deploy and retrieve metadata to and from an org. Salesforce CLI is itself a plugin.

Salesforce CLI plugins are npm (Node.js package manager) packages. Node.js is a JavaScript runtime environment that supports execution outside of a browser. If you prefer strongly typed languages, don’t worry: We recommend that you use TypeScript, which transpiles to JavaScript. Salesforce Plugin Generator’s sample plugin uses TypeScript.

We recommend using TypeScript instead of JavaScript because it's strongly typed and thus better suited to large projects. The stronger types give a better IDE experience and reduce common programming mistakes that are easy to make but hard to debug.

A user installs a plugin by running sf plugins install PLUGINNAME, where PLUGINNAME is an npm package on npmjs.com. To see your installed plugins and their versions, run sf plugins. To see which versions of the core Salesforce-provided plugins are installed on your computer, run sf plugins --core.

Why Create a Salesforce CLI Plugin?

The Salesforce CLI core plugins provide commands and functionality to meet common needs that customers and partners have. But your team probably has specific needs. That's why Salesforce CLI is extensible. Perhaps you have specific tools that you want to use for code analysis as part of your CI/CD automation process. You could build a plugin that runs your bespoke code-analysis tool. Creating a plugin provides the benefits of a consistent user experience and a common framework.

One Trailblazer plugin that’s included in the core Salesforce CLI but was developed outside the core CLI team is plugin-functions to support Salesforce Functions. With Functions, you write code in industry-standard programming languages, and run your code within the Salesforce trust boundary. The plugin contains all the Salesforce Functions-related commands to generate, deploy, run, and configure a Salesforce Function.

Because so much Salesforce functionality is surfaced in APIs, the sky's the limit as to what you can build. With Salesforce Plugin Generator, the @salesforce/sf-plugins-core and @salesforce/core libraries, and more, you have the tools you need to get started with Salesforce CLI plugin development.

Required Knowledge and Skills

Building a Salesforce CLI plugin requires different knowledge and skills than most Salesforce development. Before you dive too deeply into plugin development, familiarize yourself with these areas.

• TypeScript
• Node.js
• npm (Node.js Package Manager)
• Yarn
• Salesforce Platform APIs

Salesforce CLI Architecture

The sf executable of Salesforce CLI is an npm package called @salesforce/cli. You run it on your local machine or continuous integration (CI) system. It supports the installation of custom plugins. Most of the core functionality that Salesforce provides comes from plugins. Use Salesforce CLI for many of your development tasks, such as authorizing to any type of org, creating scratch orgs, synchronizing source code between your scratch orgs and VCS, and running tests.

All Salesforce CLI commands in the sf executable start with sf. To see which core and installed plugin version you're using, run sf plugins --core. To see the available sets of commands—also known top-level topics—run sf --help. To see a list of all available commands in an easy-to-read format, run sf commands.

Are you a visual person? Then check out this page for a graphical representation of Salesforce CLI. Be sure you scroll down to the graphic of a typical sf plugin and its libraries. Finally, see the command execution flow diagram which outlines the high-level process that occurs every time a user executes a CLI command.

Core Salesforce CLI Plugins

The core sf commands are provided by a set of core Salesforce-provided plugins that are installed by default when you install Salesforce CLI.

These core plugins contain commands in a hierarchy that reflect a typical developer's workflow. For example, the top-level topics include configuring the CLI (sf config), logging into environments (sf login), deploying and retrieving (sf deploy and sf retrieve), and managing environments (sf env). You can choose to add your commands into this hierarchy, or you can create your own top-level topics to contain your commands. It's up to you! See the Salesforce CLI Command Reference, which is also organized into this command hierarchy.

See the Salesforce CLI Status page for a list of all the core CLI plugins, their GitHub repos, and their status. The status page includes GitHub repos for both sf and sfdx plugins.

Open Source Repositories

All the code that makes up the core Salesforce CLI is open sourced in GitHub repositories, from the top-level cli package to the individual plugins, such as plugin-deploy-retrieve and plugin-login. We highly recommend that you study this code to learn the best practices of Salesforce CLI plugin development.

Open CLI Framework (oclif)

oclif is an open-source CLI framework developed by Heroku and maintained by Salesforce. It powers Heroku CLI, the core Salesforce-provided plugins, and Salesforce Plugin Generator. The plugins that you generate with Salesforce Plugin Generator use the oclif format and can take advantage of the many features that the framework offers. In addition to enabling plugin creation, this framework enables developers to create their own standalone CLI applications.

For details about oclif, see https://oclif.io/. For information about the features that oclif offers, see https://oclif.io/docs/features. For the oclif API reference, see https://oclif.io/docs/commands.

How sf and sfdx Plugin Development Differs

Many of you might be familiar with the existing Salesforce CLI Plugin Developer Guide, which describes how to create an sfdx plugin. Creating an sf plugin is very similar. For example, you still use Typescript or Javascript as the programming language, and the underlying framework is still oclif. But there are a few key differences:

• sfdx commands use the SfdxCommand base class whereas sf commands use the SfCommand base class. Both of these classes offer developers different types of functionality. For example:
  • SfdxCommand offers various properties related to working with usernames, such as supportsUsername and requiresUsername. SfCommand doesn't have these properties and instead provides custom flags. See optionalOrgFlag and requiredOrgFlag.
  • SfdxCommand automatically initializes various classes that developers are likely going to need, such as configAggregator and logger. In order to stay lighter, however, SfCommand doesn't work this way. Instead, you must initialize those classes yourself. See the API Docs for @salesforce/core for examples.
  • SfCommand provides more UX methods by default than SfdxCommand. See the API Docs for details.
• Help and error messages are stored in Markdown files rather than JSON or JavaScript.
• The style of help messages and user experience (UX) design is different. A few examples include:
  • In sf, we capitalize the beginning of command and flag descriptions, and use ending punctuation. In sfdx we kept descriptions lower-case and didn't use punctuation.
  • The human-readable table output looks different in sf.
• sf plugins have sf-specific linting rules, such as use dashes instead of camelCase in long flag names.
• Plugins that are bundled in Salesforce CLI are required to generate JSON schema for all their commands. This requirement isn't enforced for non-bundled plugins, although it's recommended.