TypeScript Adapter for SFDX CLI
Provide TS interfaces to the SFDX CLI as functions instead of executing commands on the command line. This adapter imports SFDX plugins directly instead of using the full SFDX CLI Tool. This adapter imitates CLI calls to oclif commands instead of directly calling plugin functions/classes, since only the CLI API is officially supported.
Releases
The plugins used for the released adapter version are the same as in the mentioned sfdx-cli version.
Adapter version | SFDX CLI version |
v1.2.0 | v7.147.1 |
v1.1.0 | v7.142.1 |
v1.0.0 | v7.142.1 |
Installation
You can install this by either using npm installer.
Requirements
To get started, you'll need to install node v16 (LTS) or greater. While this can be done using an installer from nodejs.com or via an OS-specific package manager.
Install package
> npm install --global @ciguru/sfdx-ts-adapter
Usage
Import adapter
import SFDX from '@ciguru/sfdx-ts-adapter';
Supported Commands
> sfdx auth:accesstoken:store
(since v1.0.0)
Call function
await SFDX.auth.accessToken.store(alias, instanceUrl, accessToken);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
alias | true | --setalias | |
instanceUrl | true | --instanceurl | |
accessToken | true | N/A | To be used as env.SFDX_ACCESS_TOKEN |
Output Data
ToBe Described
> sfdx auth:sfdxurl:store
(since v1.0.0)
Call function
await SFDX.auth.sfdxUrl.store(alias, sfdxUrlFile);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
alias | true | --setalias | |
sfdxUrlFile | true | --sfdxUrlFile |
Output Data
ToBe Described
> sfdx auth:store
(since v1.0.0)
Call function
await SFDX.auth.list();
Output Data
ToBe Described
> sfdx auth:logout
(since v1.0.0)
Call function
await SFDX.auth.logout(targetUserName);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername |
Output Data
ToBe Described
> sfdx force:apex:execute
(since v1.0.0)
Call function
await SFDX.force.apex.execute(targetUserName, apexCodeFile);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
apexCodeFile | true | --apexcodefile |
Output Data
ToBe Described
> sfdx force:apex:test:run
(since v1.0.0)
Call function
await SFDX.force.apex.test.run(targetUserName, outputDir, testLevel);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
outputDir | true | --outputdir | |
testLevel | true | --testlevel | Specifies which tests to run, using one of these TestLevel enum values: - RunSpecifiedTests—Only the tests that you specify are run (not supported yet) - RunLocalTests—All tests in your org are run, except the ones that originate from installed managed packages - RunAllTestsInOrg—All tests are in your org and in installed managed packages are run |
Output Data
ToBe Described
> sfdx force:data:bulk:delete
(since v1.2.0)
Call function
await SFDX.force.data.bulk.delete(
targetUserName,
csvFile,
sObjectType,
allowNoMoreFailedBatches,
allowNoMoreFailedRecords,
);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | Username or alias for the target org |
csvFile | true | --csvfile | Path to the CSV file containing the ids of the records to delete |
sObjectType | true | --sobjecttype | sObject type of the records you’re deleting |
allowNoMoreFailedBatches | false | N/A | Mark the transaction as successful if the number of failed batches does not exceed the specified value (default 0) |
allowNoMoreFailedRecords | false | N/A | Mark the transaction as successful if the number of failed records does not exceed the specified value (default 0) |
Output Data
ToBe Described
> sfdx force:data:bulk:upsert
(since v1.0.0)
Call function
await SFDX.force.data.bulk.upsert(
targetUserName,
csvFile,
externalId,
sObjectType,
allowNoMoreFailedBatches,
allowNoMoreFailedRecords,
);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
csvFile | true | --csvfile | |
externalId | true | --externalid | |
sObjectType | true | --sobjecttype | |
allowNoMoreFailedBatches | false | N/A | Mark the transaction as successful if the number of failed batches does not exceed the specified value (default 0) |
allowNoMoreFailedRecords | false | N/A | Mark the transaction as successful if the number of failed records does not exceed the specified value (default 0) |
Output Data
ToBe Described
> sfdx force:data:tree:import
(since v1.0.0)
Call function
await SFDX.force.data.tree.import(targetUserName, planFile);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
planFile | true | --plan |
Output Data
ToBe Described
> sfdx force:data:soql:query
(since v1.2.0)
Call function
await SFDX.force.data.soql.queryCsv(targetUserName, csvFile, query, replaceCsvHeader);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | Username or alias for the target org. |
csvFile | true | N/A | CSV file name to save output data |
query | true | --query | SOQL query to execute |
replaceCsvHeader | false | N/A | (Optional) The string value will be used to replace the CSV header row |
Output Data
ToBe Described
> sfdx force:mdapi:deploy
(since v1.0.0)
Call function
await SFDX.force.mdApi.deploy(targetUserName, testLevel, isCheckOnly, deployDir, deployZip);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
testLevel | true | --testlevel | Values: - NoTestRun - RunLocalTests - RunAllTestsInOrg - RunSpecifiedTests - not supported yet |
isCheckOnly | true | --checkonly | |
deployDir | false | --deploydir | deployDir or deployZip is required. deployDir will be used if specified both parameters |
deployZip | false | --zipfile | deployDir or deployZip is required. deployDir will be used if specified both parameters |
Output Data
ToBe Described
> sfdx force:mdapi:deploy:report
(since v1.0.0)
Call function
await SFDX.force.mdApi.deployReport(targetUserName, jobId, waitTimeout);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
jobId | true | --jobid | |
waitTimeout | false | --wait | default: 30 |
Output Data
ToBe Described
> sfdx force:mdapi:retrieve
(since v1.0.0)
Call function
await SFDX.force.mdApi.retrieve(targetUserName, retrieveTargetDir, manifestFile, packageNames);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
retrieveTargetDir | true | --retrievetargetdir | |
manifestFile | true | --unpackaged | manifestFile or packageNames is required. manifestFile will be used if specified both parameters |
packageNames | true | --packagenames | manifestFile or packageNames is required. manifestFile will be used if specified both parameters |
Output Data
ToBe Described
> sfdx force:org:create
(since v1.0.0)
Call function
await SFDX.force.org.create.scratch(alias, isNoAncestors, definitionFile, devHubUserName, duration, overrideDefinition);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
alias | true | --setalias | |
isNoAncestors | true | --noancestors | |
definitionFile | true | --definitionfile | |
devHubUserName | true | --targetdevhubusername | |
duration | true | --durationdays | |
overrideDefinition.adminEmail | false | Command argument: adminEmail= |
Output Data
ToBe Described
> sfdx force:org:delete
(since v1.0.0)
Call function
await SFDX.force.org.delete(targetUsername, devHubUserName);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
devHubUserName | true | --targetdevhubusername |
Output Data
ToBe Described
> sfdx force:org:display
(since v1.0.0)
Call function
await SFDX.force.org.display(targetUsername);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername |
Output Data
ToBe Described
> sfdx force:package:install
(since v1.0.0)
Call function
await SFDX.force.package.install(targetUserName, packageId);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
packageId | true | --package |
Output Data
ToBe Described
> sfdx force:source:convert
(since v1.1.0)
Call function
await SFDX.force.source.convert(outputDir, sourcePath);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
outputDir | true | --outputdir | Output directory to store the Metadata API–formatted files in |
sourcePath | false | --sourcepath | Array of paths to the local source files to convert |
Output Data
ToBe Described
> sfdx force:source:push
(since v1.0.0)
Call function
await SFDX.force.source.push(targetUserName, isForceOverwrite);
Parameters
Parameter | Required | SFDX Command attribute | Comment |
targetUserName | true | --targetusername | |
isForceOverwrite | false | --forceoverwrite |
Output Data
ToBe Described