-
Notifications
You must be signed in to change notification settings - Fork 21
Conceptual Overview of Salesforce CLI
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
.
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.
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
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.
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.
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.
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.
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 theSfdxCommand
base class whereassf
commands use theSfCommand
base class. Both of these classes offer developers different types of functionality. For example:-
SfdxCommand
offers various properties related to working with usernames, such assupportsUsername
andrequiresUsername
.SfCommand
doesn't have these properties and instead provides custom flags. SeeoptionalOrgFlag
andrequiredOrgFlag
. -
SfdxCommand
automatically initializes various classes that developers are likely going to need, such asconfigAggregator
andlogger
. 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 thanSfdxCommand
. 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. Insfdx
we kept descriptions lower-case and didn't use punctuation. - The human-readable table output looks different in
sf
.
- In
-
sf
plugins havesf
-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.
© Copyright 2024 Salesforce.com, inc. All rights reserved. Various trademarks held by their respective owners.
- Quick Intro to Developing sf Plugins
- Get Started: Create Your First Plugin
- Design Guidelines
- Code Your Plugin
- Debug Your Plugin
- Write Useful Messages
- Test Your Plugin
- Maintain Your Plugin
- Integrate Your Plugin With the Doctor Command
- Migrate Plugins Built for sfdx
- Conceptual Overview of Salesforce CLI