SFDX-Node

Wrapper for the Salesforce CLI to use in Node.js

Installation

npm install sfdx-node

Usage

The Salesforce CLI is based on OCLIF and is a combination of different OCLIF plugins. This module includes all the commands in force, auth
and config namespaces. To use Salesforce CLI commands within Node.js programs, we wrap the namespace, topics, and camelcase the commands.
For example:
- sfdx force:org:list becomes sfdx.force.org.list()
- sfdx force:package:version:create becomes sfdx.force.package.versionCreate()
- sfdx auth:web:login becomes sfdx.auth.web.login()
- sfdx config:set becomes sfdx.config.set()

> sfdx NAMESPACE:TOPIC:COMMAND:SUB -> sfdx.namespace.topic.commandSub();

Command parameters can be passed in as an object to the command using the flag names. So sfdx force:org:create --setalias myorg --setdefaultusername
can be executed as below:

``javascript
const sfdx = require('sfdx-node');

// Create a new scratch org with alias myorg and set it as default org
sfdx.force.org.create({
setalias: 'myorg',
setdefaultusername: true
});
`

Similarly, the special command arguments can be passing in as an array named args inside an object, as the second method argument.
So, sfdx alias:set myorg1=test-user1@example.com myorg2=test-user2@example.com can be executed as below:

`javascript
const sfdx = require('sfdx-node');

// Set/overwrite aliases for already authorized orgs
sfdx.alias.set({},{
args: ['myorg1=test-user1@example.com', 'myorg2=test-user2@example.com']
});
`

Commands all return a JS Promise.

`javascript
const sfdx = require('sfdx-node');

//authorize a dev hub
sfdx.auth.web.login({
setdefaultdevhubusername: true,
setalias: 'HubOrg'
})
.then(() => sfdx.force.source.push()) //push source
.then(() => {
// Display confirmation of source push
console.log('Source pushed to scratch org');
});
`

Using _quiet for showing/hiding command output

It is possible to control the visibility of the output (success or failure) generated by a Salesforce CLI command, executed through this module.
Output can be made visible by passing in the flag _quiet as false. Default value for flag _quiet is true, which means that the default
behavior of this module is to hide the output of a Salesforce CLI command.

`javascript
const sfdx = require('sfdx-node');

// Fetch all the aliases, but do not show how the Salesforce CLI command output
sfdx.alias.list()
.then((listResult) => {
// Do something with the fetched list of all aliases
console.log('Alias list:', listResult);
});

// Fetch all the aliases, and show the Salesforce CLI command output
sfdx.alias.list({
_quiet: false
})
.then((listResult) => {
// Do something else with the fetched list of all aliases
});
`




Using _rejectOnError for promise rejection (in case of a command failure)

Majority of the Salesforce CLI commands, when executed through node, do not reject the promise when an error occurs. They rather resolve with
undefined. Promise rejection can be forced by passing in the flag _rejectOnError as true. A few Salesforce CLI commands reject the promise
as their out-of-the-box behavior, without using this _rejectOnError flag.

`javascript
const sfdx = require('sfdx-node');

// Pull the remote changes from the scratch org
sfdx.force.source.pull({
_rejectOnError: true
})
.then((pullResult) => {
// Successfully pulled from scratch org
console.log('Changes pulled from scratch org:', pullResult);
})
.catch((pullError) => {
// Promise rejected in case of conflicts or some other issue while pulling from scratch org
console.log('Errors occurred during pull operation:', pullError);
});
`

Rejecting promises is not the default bahavior of this module, unless the promise is rejected by Salesforce CLI command itself. This _rejectOnError
flag needs to be passed in as true for every command that is expected to reject the promise in case of an error.

$3

When multiple CLI commands are executed in parallel using this module, while also making use of _rejectOnError, more than one or even all the commands
may end up rejecting the promises. This can happen because the errors are shared among all the parallel executions.

To avoid this, make use of sfdx-node/parallel module. It works in the same way as the main module, except for the fact that each command is executed in
it's own child process. This ensures that each command execution has it's own context and it doesn't share errors with other commands executing in parallel.

`javascript
const sfdx = require('sfdx-node/parallel');

// Get source status for first scratch org
sfdx.force.source.status({
targetusername: 'test-user1@example.com',
_rejectOnError: true
})
.then((statusResult) => {
// Source status for first scratch org
console.log('First org source status:', statusResult);
})
.catch((statusError) => {
// Error occurred during source status check for first scratch org
console.log('First org error:', statusError);
});

// Get source status for second scratch org
sfdx.force.source.status({
targetusername: 'test-user2@example.com',
_rejectOnError: true
})
.then((statusResult) => {
// Source status for second scratch org
console.log('Second org source status:', statusResult);
})
.catch((statusError) => {
// Error occurred during source status check for second scratch org
console.log('Second org error:', statusError);
});
``