@salesforce/command
Advanced tools
@salesforce/command is an npm package that provides a framework for building CLI commands for Salesforce. It is designed to help developers create commands that interact with Salesforce APIs and services, making it easier to automate tasks and integrate Salesforce with other systems.
Command Creation
This feature allows developers to create custom CLI commands by extending the SfdxCommand class. The example demonstrates a simple command that logs a message to the console.
const { SfdxCommand } = require('@salesforce/command');
class MyCommand extends SfdxCommand {
async run() {
this.ux.log('Hello, Salesforce!');
}
}
module.exports = MyCommand;Parameter Handling
This feature provides a way to define and handle command-line parameters using the flags property. The example shows how to define a 'name' parameter and use it within the command.
const { flags, SfdxCommand } = require('@salesforce/command');
class MyCommand extends SfdxCommand {
static flagsConfig = {
name: flags.string({ char: 'n', description: 'name to print' })
};
async run() {
const name = this.flags.name || 'world';
this.ux.log(`Hello, ${name}!`);
}
}
module.exports = MyCommand;Salesforce Authentication
This feature allows commands to authenticate and interact with Salesforce orgs. The example demonstrates how to create a connection and query Salesforce data.
const { SfdxCommand } = require('@salesforce/command');
const { Connection } = require('@salesforce/core');
class MyCommand extends SfdxCommand {
async run() {
const conn = await Connection.create({ authInfo: this.org.getConnection().getAuthInfo() });
const result = await conn.query('SELECT Id, Name FROM Account');
this.ux.logJson(result.records);
}
}
module.exports = MyCommand;oclif is a framework for building command-line interfaces in Node.js. It is highly extensible and supports plugins, making it suitable for creating complex CLI applications. Compared to @salesforce/command, oclif is more general-purpose and not specifically tailored for Salesforce.
commander is a popular Node.js library for building command-line interfaces. It provides a simple and flexible API for defining commands and options. While it is not specifically designed for Salesforce, it can be used to create CLI tools for various purposes, including Salesforce automation.
yargs is another widely-used library for building command-line tools in Node.js. It offers a rich set of features for parsing arguments and generating help messages. Like commander, yargs is a general-purpose library and can be used to create CLI tools for different use cases, including Salesforce.
This is the base command class for the Salesforce CLI. Extend this class for convenient access to common Salesforce CLI parameters, a logger, CLI output formatting, scratch orgs, and Dev Hubs. This class extends @oclif/command and is available within a plugin generated by the Salesforce Plugin Generator.
As a beta feature, the SfdxCommand class is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for the SfdxCommand class in the issues section of this repo.
Commands that extend SfdxCommand can only be used with Salesforce CLI version 6.8.2 or later. To check your Salesforce CLI version:
$ sfdx --version
There are many features that can be enabled with SfdxCommand subclasses simply by setting static properties on the subclassed command. Other features are always available for your command, such as a logger and output renderer.
SfdxCommand has a handful of static properties for easy toggling of Salesforce CLI features such as adding a scratch org to your command instance or requiring a command to run from within a Salesforce DX project.SfdxCommand subclasses have the --json and --loglevel parameters automatically added to their command. Other Salesforce CLI parameters are enabled either by setting static properties directly on the command or within the flagsConfig static property.varargs static property, which enables 0 to n key=value pairs to be accepted as command input.SfdxError is not thrown then the error handler wraps the error in an SfdxError for consistent error display.true to add the --targetusername (-u) and --apiversion flags to this command, and to have the org added (if provided) as an instance property which you can access in your command as this.org.static supportsUsername = true;
true to add the --targetusername (-u) and --apiversion flags to this command and to require that a target username is set, either via the flag or by having a default set in your Salesforce CLI config.static requiresUsername = true;
true to add the --targetdevhubusername (-v) and --apiversion flags to this command, and to have the dev hub org added (if provided) as an instance property which you can access in your command as this.hubOrg.static supportsDevhubUsername = true;
true to add the --targetdevhubusername (-v) and --apiversion flags to this command and to require that a target dev hub username is set, either via the flag or by having a default set in your Salesforce CLI config.static requiresDevhubUsername = true;
true if this command must be run within a Salesforce DX project, and to have the project object added as an instance property which you can access in your command as this.project.static requiresProject = true;
static flagsConfig = {
name: {char: 'n', type: 'string', description: messages.getMessage('nameFlagDescription')},
force: {char: 'f', type: 'boolean'},
quiet: true
};
true to enable key=value parameter input to the command. To require at least one vararg, or to define a varargs validator function, use the VarargsConfig object definition. Be sure to throw an error from the validator function with a helpful error message and action when validation fails.static varargs = true;
static varargs = {
required: true,
validator: (name, value) => {
// Whitelist varargs parameter names
if (!myWhitelist.includes(name)) {
const errMsg = `Invalid parameter [${name}] found`;
const errName = 'InvalidVarargName';
const errAction = `Please choose from this list of parameter names: ${myWhitelist.join()}`;
throw new SfdxError(errMsg, errName, [errAction]);
}
}
}
static tableColumnData = ['id', 'name', 'description'];
static result = {
tableColumnData: [
{key: 'id', label: 'ID'},
{key: 'name', label: 'Name'},
{key: 'description', label: 'Description'}
],
display(): {
if (Array.isArray(this.data) && this.data.length) {
if (this.data.length > 100) {
// special display for large number of results
} else {
this.ux.table(this.data, this.tableColumnData);
}
}
}
};
--targetusername (-u) flag or a default defined in the Salesforce CLI config.--targetdevhubusername (-v) flag or a default defined in the Salesforce CLI config.--json flag so that output is supressed when set.run method has completed.Extending SfdxCommand makes many Salesforce CLI parameters and parameter types available. As mentioned above, some of these parameters are added when static properties are set on your command (such as supportsUsername), some are added by default (such as --json and --loglevel), and some can be added or removed from your command via the flagsConfig static property. You can also override the flags implementation completely by defining your own static flags property. See the oclif flags docs for details.
Global Salesforce CLI Parameters These parameters are either available by default or used by many Salesforce CLI commands. Global parameters do not have short names.
json - Suppresses output from this.ux.* methods and formats output as JSON. This flag is available by default on all Salesforce CLI commands. Its value treated as true if provided, false otherwise.loglevel - Sets the logging level for this command invocation. Logs are stored in $HOME/.sfdx/sfdx.log. This enum flag accepts only known (lowercase) logging options and is available on all Salesforce CLI commands. See the LoggerLevel docs for more info.apiversion - Overrides the default apiVersion for API requests made by this command.targetusername - Sets a username or alias for the target org. Overrides the default target org.targetdevhubusername - Sets a username or alias for the target Dev Hub org. Overrides the default Dev Hub org.concise - A common flag name to use for writing brief command output to stdout. Your command is responsible for modifying output based on this flag. This flag's value is treated as true if provided, false otherwise.quiet - A common flag name to use for suppressing command output to stdout. Your command is responsible for modifying output based on this flag. This flag's value is treated as true if provided, false otherwise.verbose - A common flag name to use for additional command output to stdout. Your command is responsible for modifying output based on this flag. This flag's value is treated as true if provided, false otherwise.Salesforce CLI Parameter Types
You can use more specific parameter types when defining flags for your command. This will provide some validation for the format of the parameter values, and give users a better idea of the expected value for the parameter. In addition to the types listed below, there are also the oclif flag types of string and boolean.
array - The parameter expects an array of comma-separated values. For example: first,second,third or "first name, last name, suffix"date - The parameter expects a date. For example: 01-02-2000datetime - The parameter expects a datetime. For example: "01/02/2000 01:02:34"directory - The parameter expects a path to a directory. For example: /my/path/toemail - The parameter expects an email address. For example: me@example.comfilepath - The parameter expects a filepath. For example: /my/path/to/myfile.jsonid - The parameter expects a Salesforce ID. For example: 00Dxxxxxxxxxxxxnumber - The parameter expects a number. For example: 42time - The parameter expects a time. For example: 01:02:03url - The parameter expects a URL. For example: https://www.salesforce.comExample
static flagsConfig = {
names: {char: 'n', required: true, type: 'array'}, // use a Salesforce CLI parameter type
force: flags.boolean({char: 'f'}), // use an oclif flag builder
verbose: true, // enable the SFDX verbose flag
apiversion: false, // disable the SFDX apiversion flag
targetusername: {required: true} // override default targetusername behavior by making it required
};
SfdxCommand handles runtime errors in the catch method for consistent error-handling format and behavior. By default, the exit code will be 1 unless otherwise specified within the SfdxError. Stack traces are suppressed unless the SFDX_ENV environment variable's value is set to development. Override the catch method if you'd prefer to handle errors within your command.
FAQs
Salesforce CLI base command class
The npm package @salesforce/command receives a total of 97,224 weekly downloads. As such, @salesforce/command popularity was classified as popular.
We found that @salesforce/command demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 54 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.