SfdxCommand (Beta)

• Description
• Requirements
• Features
  • Static Properties
  • Instance Properties
  • SFDX Flags
  • Table Rendering
  • Error Handling
• Related Docs and Repositories

Description

This is the base command class that plugin command authors will extend for convenient access to common SFDX flags, a logger, CLI output formatting, scratch orgs, and devhubs. It extends @oclif/command and is available within a plugin generated by the Salesforce Plugin Generator.

As a beta feature, the Salesforce command module 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 Salesforce command module in the issues section of this repo.

Requirements

$ sfdx --version

Commands that extend SfdxCommand can only be used with SFDX CLI version 6.8.2 or later.

Features

There are many features that can be enabled with SfdxCommand subclasses simply by setting static properties on the subclassed command. Other features will always be available for your command such as a logger and output renderer.

• Static Properties - SfdxCommand has a handful of static properties for easy toggling of SFDX features such as requiring a command to run from within an SFDX project or adding a scratch org to your command instance.
• Instance Properties - Many instance properties are added to your command for convenient access to orgs, dev hub orgs, project files, flags, and more.
• SFDX Flags - All SfdxCommand subclasses will have the --json and --loglevel flags automatically added to their command. Other SFDX Flags are enabled either by setting static properties directly on the command or within the flagsConfig static property.
• 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 it 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 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 require that a targetusername is set, either via the flag or by having a default set in your SFDX config.

static requiresUsername = true;

• supportsDevhubUsername - Set to true to add the --targetdevhubusername (-v) and --apiversion flags to this command, and 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 require that a targetdevhubusername is set, either via the flag or by having a default set in your SFDX config.

static requiresDevhubUsername = true;

• requiresProject - Set to true if this command must be run within a SFDX project, and 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 SFDX flags, as well as configure new flags.

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

• 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 from the command line.
• org - The org associated with the username provided via --targetusername (-u) flag or a default defined in the SFDX config.
• hubOrg - The devhub org associated with the username provided via --targetdevhubusername (-v) flag or a default defined in the SFDX config.
• project - The SFDX project object.
• configAggregator - The SfdxConfigAggregator object.
• logger - The SFDX 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.

SFDX Flags

There are many SFDX flags and flag types made available by extending SfdxCommand. As mentioned above, some of these flags are added when static properties are set on your command such as supportsUsername, some are added necessarily 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.

• SFDX Flags
  • json - Supresses output from this.ux.* methods and formats output as JSON. A boolean flag that is necessarily on all SfdxCommands.
  • loglevel - Sets the logging level for this command invocation. Logs are stored in $HOME/.sfdx/sfdx.log. An enum flag that only accepts known (lowercase) logging options and on all SfdxCommands. See LoggerLevel docs for more info.
  • apiversion - Overrides the API version used 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, boolean flag name to use for brief command output to stdout. Your command is responsible for modifying output based on this flag.
  • quiet - A common, boolean flag name to use for suppressing command output to stdout. Your command is responsible for modifying output based on this flag.
  • verbose - A common, boolean flag name to use for additional command output to stdout. Your command is responsible for modifying output based on this flag.
• Sfdx Flag Types You can use more specific flag types when defining flags for your command. This will provide some validation for the format of the flag values, and give users a better idea of the expected value for the flag.
  • array - The flag expects an array of comma-separated values. E.g., --myflag=first,second,third
  • date - The flag expects a date. E.g., --myflag=01-02-2000
  • datetime - The flag expects a datetime. E.g., --myflag=01/02/2000 01:02:34
  • directory - The flag expects a directory. E.g., --myflag=/my/path/to
  • email - The flag expects an email address. E.g., --myflag=me@my.org
  • filepath - The flag expects a filepath. E.g., --myflag=/my/path/to/myfile.json
  • id - The flag expects a Salesforce ID. E.g., --myflag=00Dxxxxxxxxxxxx
  • number - The flag expects a number. E.g., --myflag=42
  • time - The flag expects a time. E.g., --myflag=01:02:03
  • url - The flag expects a URL. E.g., --myflag=http://www.salesforce.com
• Example

static flagsConfig = {
    names: {name: 'names', char: 'n', required: true, type: 'array'}, // use an SFDX flag 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
};

by specifying that your command supports a username your command will automatically have the --targetusername (-u) and apiversion flags added. The --json and --loglevel flags are also added by default.

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 supressed unless the SFDX_ENV environment variable is set to "development". Override the catch method if you'd prefer to handle errors within your command.