@salesforce/command

What is @salesforce/command?

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

What are @salesforce/command's main functionalities?

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;

Other packages similar to @salesforce/command

oclif

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

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

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.

README

SfdxCommand (Beta)

• Description
• Requirements
• Features
  • Static Properties
  • Instance Properties
  • Salesforce CLI Parameters
  • Varargs Parameters
  • Table Rendering
  • Error Handling

Description

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.

---

Requirements

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

Features

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.

• Static Properties - 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.
• Instance Properties - Many instance properties are added to your command for convenient access to orgs (including Dev Hubs), project files, parameters, and more.
• Salesforce CLI Parameters - All 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 Parameters - Varargs-style parameters are enabled via the varargs static property, which enables 0 to n key=value pairs to be accepted as command input.
• Table Rendering - It's easy for your command to output results in a table format. Simple table formatting is defined with the tableColumnData static property. For complete control over rendering use the result static property.
• Error Handling - Errors thrown during the command lifecycle are handled for you. If an SfdxError is not thrown then the error handler wraps the error in an SfdxError for consistent error display.

Static Properties

• supportsUsername - Set to 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;

• requiresUsername - Set to 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;

• supportsDevhubUsername - Set to 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;

• requiresDevhubUsername - Set to 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;

• requiresProject - Set to 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;

• flagsConfig - Use this property to enable, disable, or override Salesforce CLI parameters, and to configure new parameters.

static flagsConfig = {
    name: {char: 'n', type: 'string', description: messages.getMessage('nameFlagDescription')},
    force: {char: 'f', type: 'boolean'},
    quiet: true
};

• varargs - Set to 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]);
        }
    }
}

• tableColumnData - Use this string array to define table columns for simple command output table formatting.

static tableColumnData = ['id', 'name', 'description'];

• result - Use for full control over command output formatting and display, or to override certain pieces of default display behavior. See oclif/cli-ux table for more granular details of table rendering.

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);
            }
        }
    }
};

Instance Properties

• args - The parsed args from the command line.
• flags - The parsed flags (parameters) from the command line.
• org - The org associated with the username provided via the --targetusername (-u) flag or a default defined in the Salesforce CLI config.
• hubOrg - The Dev Hub org associated with the username provided via the --targetdevhubusername (-v) flag or a default defined in the Salesforce CLI config.
• project - The Salesforce DX project object.
• configAggregator - The SfdxConfigAggregator object.
• logger - The Salesforce CLI logger.
• ux - The UX object for command output. The UX methods respect the --json flag so that output is supressed when set.
• result - The result instance where data and formatting can be manipulated after the command's run method has completed.

Salesforce CLI Parameters

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-2000
  • datetime - 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/to
  • email - The parameter expects an email address. For example: [e-mail]
  • filepath - The parameter expects a filepath. For example: /my/path/to/myfile.json
  • id - The parameter expects a Salesforce ID. For example: 00Dxxxxxxxxxxxx
  • number - The parameter expects a number. For example: 42
  • time - The parameter expects a time. For example: 01:02:03
  • url - The parameter expects a URL. For example: https://www.salesforce.com

• Example

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
};

Error Handling

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.