@salesforce/core

@salesforce/core

Version 3.33.1
Published 11 days ago
903 kB
17 dependencies
BSD-3-Clause license

Install

npm i @salesforce/core

yarn add @salesforce/core

pnpm add @salesforce/core

Overview

Core libraries to interact with SFDX projects, orgs, and APIs.

Index

Variables

variable envVars

const envVars: EnvVars;

variable ORG_CONFIG_ALLOWED_PROPERTIES

const ORG_CONFIG_ALLOWED_PROPERTIES: (
    | {
          key: OrgConfigProperties;
          description: string;
          input?: undefined;
          hidden?: undefined;
          encrypted?: undefined;
      }
    | {
          key: OrgConfigProperties;
          description: string;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          hidden?: undefined;
          encrypted?: undefined;
      }
    | {
          key: OrgConfigProperties;
          description: string;
          hidden: boolean;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          encrypted?: undefined;
      }
    | {
          key: OrgConfigProperties;
          description: string;
          encrypted: boolean;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          hidden?: undefined;
      }
)[];

variable REQUIRED_FIELDS

const REQUIRED_FIELDS: {
    id: string;
    username: string;
    lastName: string;
    alias: string;
    timeZoneSidKey: string;
    localeSidKey: string;
    emailEncodingKey: string;
    profileId: string;
    languageLocaleKey: string;
    email: string;
};

A Map of Required Salesforce User fields.

variable scratchOrgLifecycleEventName

const scratchOrgLifecycleEventName: string;

variable scratchOrgLifecycleStages

const scratchOrgLifecycleStages: readonly [
    'prepare request',
    'send request',
    'wait for org',
    'available',
    'authenticate',
    'deploy settings',
    'done'
];

variable SF_ALLOWED_PROPERTIES

const SF_ALLOWED_PROPERTIES: {
    key: SfConfigProperties;
    description: string;
    input: { validator: (value: AnyJson) => boolean; failedMessage: string };
}[];

variable sfdc

const sfdc: {
    trimTo15: typeof trimTo15;
    validateApiVersion: (value: string) => boolean;
    validateEmail: (value: string) => boolean;
    isInternalUrl: (url: string) => boolean;
    matchesAccessToken: (value: string) => boolean;
    validateSalesforceId: (value: string) => boolean;
    validatePathDoesNotContainInvalidChars: (value: string) => boolean;
    findUpperCaseKeys: (
        data?: JsonMap,
        sectionBlocklist?: string[]
    ) => Optional<string>;
};

Deprecated
import the individual functions instead of the whole object

variable SFDX_ALLOWED_PROPERTIES

const SFDX_ALLOWED_PROPERTIES: (
    | {
          key: SfdxPropertyKeys;
          description: string;
          newKey: OrgConfigProperties;
          deprecated: boolean;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          encrypted?: undefined;
          hidden?: undefined;
      }
    | {
          key: SfdxPropertyKeys;
          newKey: OrgConfigProperties;
          deprecated: boolean;
          description: string;
          input?: undefined;
          encrypted?: undefined;
          hidden?: undefined;
      }
    | {
          key: SfdxPropertyKeys;
          newKey: OrgConfigProperties;
          deprecated: boolean;
          description: string;
          encrypted: boolean;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          hidden?: undefined;
      }
    | {
          key: SfdxPropertyKeys;
          newKey: SfConfigProperties;
          deprecated: boolean;
          description: string;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          encrypted?: undefined;
          hidden?: undefined;
      }
    | {
          key: SfdxPropertyKeys;
          description: string;
          hidden: boolean;
          newKey: string;
          deprecated: boolean;
          input: { validator: (value: AnyJson) => boolean; failedMessage: string };
          encrypted?: undefined;
      }
)[];

variable SFDX_HTTP_HEADERS

const SFDX_HTTP_HEADERS: { 'content-type': string; 'user-agent': string };

variable SUPPORTED_ENV_VARS

const SUPPORTED_ENV_VARS: EnvType;

Functions

function findUpperCaseKeys

findUpperCaseKeys: (
    data?: JsonMap,
    sectionBlocklist?: string[]
) => Optional<string>;

Returns the first key within the object that has an upper case first letter.
Parameter data
The object in which to check key casing.
Parameter sectionBlocklist
properties in the object to exclude from the search. e.g. a blocklist of ["a"] and data of { "a": { "B" : "b"}} would ignore B because it is in the object value under a.

function getJwtAudienceUrl

getJwtAudienceUrl: (
    options: OAuth2Config & { createdOrgInstance?: string }
) => Promise<string>;

function getLoginAudienceCombos

getLoginAudienceCombos: (
    audienceUrl: string,
    loginUrl: string
) => Array<[string, string]>;

function isInternalUrl

isInternalUrl: (url: string) => boolean;

Tests whether a given url is an internal Salesforce domain
Parameter url

function matchesAccessToken

matchesAccessToken: (value: string) => boolean;

Tests whether a given string is an access token
Parameter value

function scratchOrgCreate

scratchOrgCreate: (
    options: ScratchOrgCreateOptions
) => Promise<ScratchOrgCreateResult>;

function scratchOrgResume

scratchOrgResume: (jobId: string) => Promise<ScratchOrgCreateResult>;

function trimTo15

trimTo15: {
    (id: string): string;
    (id?: undefined): undefined;
    (id: string): string;
};

Converts an 18 character Salesforce ID to 15 characters.
Parameter id
The id to convert.

function validateApiVersion

validateApiVersion: (value: string) => boolean;

Tests whether an API version matches the format i.0.
Parameter value
The API version as a string.

function validateEmail

validateEmail: (value: string) => boolean;

Tests whether an email matches the format me@my.org
Parameter value
The email as a string.

function validatePathDoesNotContainInvalidChars

validatePathDoesNotContainInvalidChars: (value: string) => boolean;

Tests whether a path is in the correct format; the value doesn't include the characters "[", "]", "?", "<", ">", "?", "|"
Parameter value
The path as a string.

function validateSalesforceId

validateSalesforceId: (value: string) => boolean;

Tests whether a Salesforce ID is in the correct format, a 15- or 18-character length string with only letters and numbers
Parameter value
The ID as a string.

Classes

class AuthInfo

class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {}

Handles persistence and fetching of user authentication information using JWT, OAuth, or refresh tokens. Sets up the refresh flows that jsForce will use to keep tokens active. An AuthInfo can also be created with an access token, but AuthInfos created with access tokens can't be persisted to disk.
**See** [Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth.htm)
**See** [Salesforce DX Usernames and Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_usernames_orgs.htm)
// Creating a new authentication file. const authInfo = await AuthInfo.create({ username: myAdminUsername, oauth2Options: { loginUrl, authCode, clientId, clientSecret } ); authInfo.save(); // Creating an authorization info with an access token. const authInfo = await AuthInfo.create({ username: accessToken }); // Using an existing authentication file. const authInfo = await AuthInfo.create({ username: myAdminUsername }); // Using the AuthInfo const connection = await Connection.create({ authInfo });

constructor

constructor(options?: AuthInfo.Options);

Constructor **Do not directly construct instances of this class -- use AuthInfo.create instead.**
Parameter options
The options for the class instance

method getAuthorizationUrl

static getAuthorizationUrl: (
    options: JwtOAuth2Config & { scope?: string },
    oauth2?: OAuth2
) => string;

Get the authorization URL.
Parameter options
The options to generate the URL.

method getClientId

getClientId: () => string;

method getConnectionOptions

getConnectionOptions: () => ConnectionOptions;

Get the auth fields (decrypted) needed to make a connection.

method getDefaultInstanceUrl

static getDefaultInstanceUrl: () => string;

Returns the default instance url
Returns
{string}

method getDevHubAuthInfos

static getDevHubAuthInfos: () => Promise<OrgAuthorization[]>;

Find all dev hubs available in the local environment.

method getFields

getFields: (decrypt?: boolean) => AuthFields;

Get the authorization fields.
Parameter decrypt
Decrypt the fields.

method getOrgFrontDoorUrl

getOrgFrontDoorUrl: () => string;

Get the org front door (used for web based oauth flows)

method getRedirectUri

getRedirectUri: () => string;

method getSfdxAuthUrl

getSfdxAuthUrl: () => string;

Get the SFDX Auth URL.
**See** [SFDX Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_auth.htm#cli_reference_force_auth)

method handleAliasAndDefaultSettings

handleAliasAndDefaultSettings: (sideEffects: AuthSideEffects) => Promise<void>;

Convenience function to handle typical side effects encountered when dealing with an AuthInfo. Given the values supplied in parameter sideEffects, this function will set auth alias, default auth and default dev hub.
Parameter sideEffects
instance of AuthSideEffects

method hasAuthentications

static hasAuthentications: () => Promise<boolean>;

Returns true if one or more authentications are persisted.

method identifyPossibleScratchOrgs

static identifyPossibleScratchOrgs: (
    fields: AuthFields,
    orgAuthInfo: AuthInfo
) => Promise<void>;

Given a set of decrypted fields and an authInfo, determine if the org belongs to an available dev hub.
Parameter fields
Parameter orgAuthInfo

method init

init: () => Promise<void>;

Initializes an instance of the AuthInfo class.

method isAccessTokenFlow

isAccessTokenFlow: () => boolean;

Returns true if this is using an access token flow.

method isJwt

isJwt: () => boolean;

Returns true if this is using the JWT flow.

method isOauth

isOauth: () => boolean;

Returns true if this is using the oauth flow.

method isRefreshTokenFlow

isRefreshTokenFlow: () => boolean;

Returns true if this is using the refresh token flow.

method isUsingAccessToken

isUsingAccessToken: () => boolean;

Returns true if this org is using access token auth.

method listAllAuthorizations

static listAllAuthorizations: (
    orgAuthFilter?: (orgAuth: OrgAuthorization) => boolean
) => Promise<OrgAuthorization[]>;

Get a list of all authorizations based on auth files stored in the global directory. One can supply a filter (see
Parameter orgAuthFilter
) and calling this function without a filter will return all authorizations.
Parameter orgAuthFilter
A predicate function that returns true for those org authorizations that are to be retained.
Returns
{Promise<OrgAuthorization[]>}

method parseSfdxAuthUrl

static parseSfdxAuthUrl: (
    sfdxAuthUrl: string
) => Pick<AuthFields, 'clientId' | 'clientSecret' | 'refreshToken' | 'loginUrl'>;

Parse a sfdx auth url, usually obtained by authInfo.getSfdxAuthUrl.
Parameter sfdxAuthUrl
Example 1
await AuthInfo.create(AuthInfo.parseSfdxAuthUrl(sfdxAuthUrl));

method save

save: (authData?: AuthFields) => Promise<AuthInfo>;

Updates the cache and persists the authentication fields (encrypted).
Parameter authData
New data to save.

method setAlias

setAlias: (alias: string) => Promise<void>;

Sets the provided alias to the username
Parameter alias
alias to set

method setAsDefault

setAsDefault: (options?: { org?: boolean; devHub?: boolean }) => Promise<void>;

Set the target-env (default) or the target-dev-hub to the alias if it exists otherwise to the username. Method will try to set the local config first but will default to global config if that fails.
Parameter options

method update

update: (authData?: AuthFields) => AuthInfo;

Update the authorization fields, encrypting sensitive fields, but do not persist. For convenience this object is returned.
Parameter authData
Authorization fields to update.

class AuthRemover

class AuthRemover extends AsyncOptionalCreatable {}

Handles the removing of authorizations, which includes deleting the auth file in the global .sfdx folder, deleting any configs that are associated with the username/alias, and deleting any aliases associated with the username

const remover = await AuthRemover.create();
await remover.removeAuth('example@mycompany.com');

const remover = await AuthRemover.create();
await remover.removeAllAuths();

const remover = await AuthRemover.create();
const auth = await remover.findAuth(
 example@mycompany.com
);
await remover.removeAuth(auth.username);

method findAllAuths

findAllAuths: () => Record<string, AuthFields & JsonMap>;

Finds all org authorizations in the global info file (.sf/sf.json)
Returns
{Record<string, AuthFields>}

method findAuth

findAuth: (usernameOrAlias?: string) => Promise<AuthFields>;

Finds authorization files for username/alias in the global .sfdx folder **Throws** *SfError{ name: 'TargetOrgNotSetError' }* if no target-org **Throws** *SfError{ name: 'NamedOrgNotFoundError' }* if specified user is not found
Parameter usernameOrAlias
username or alias of the auth you want to find, defaults to the configured target-org
Returns
{Promise}

method init

protected init: () => Promise<void>;

method removeAllAuths

removeAllAuths: () => Promise<void>;

Removes all authentication files and any configs or aliases associated with them

method removeAuth

removeAuth: (usernameOrAlias: string) => Promise<void>;

Removes the authentication and any configs or aliases associated with it
Parameter usernameOrAlias
the username or alias that you want to remove

class CometClient

abstract class CometClient extends EventEmitter {}

Comet client interface. The is to allow for mocking the inner streaming Cometd implementation. The Faye implementation is used by default but it could be used to adapt another Cometd impl.

method addExtension

abstract addExtension: (extension: StreamingExtension) => void;

Add a custom extension to the underlying client.
Parameter extension
The json function for the extension.

method disable

abstract disable: (label: string) => void;

Disable polling features.
Parameter label
Polling feature label.

method disconnect

abstract disconnect: () => void;

Method to call to disconnect the client from the server.

method handshake

abstract handshake: (callback: () => void) => void;

handshake with the streaming channel
Parameter callback
Callback for the handshake when it successfully completes. The handshake should throw errors when errors are encountered.

method setHeader

abstract setHeader: (name: string, value: string) => void;

Sets an http header name/value.
Parameter name
The header name.
Parameter value
The header value.

abstract subscribe: (
    channel: string,
    callback: (message: JsonMap) => void
) => CometSubscription;

Subscribes to Comet topics. Subscribe should perform a handshake if one hasn't been performed yet.
Parameter channel
The topic to subscribe to.
Parameter callback
The callback to execute once a message has been received.

class Config

class Config extends ConfigFile<ConfigFile.Options, ConfigProperties> {}

The files where sfdx config values are stored for projects and the global space.
*Note:* It is not recommended to instantiate this object directly when resolving config values. Instead use ConfigAggregator
const localConfig = await Config.create(); localConfig.set('target-org', 'username@company.org'); await localConfig.write();
https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_config_values.htm

constructor

constructor(options?: ConfigFile.Options);

method addAllowedProperties

static addAllowedProperties: (metas: ConfigPropertyMeta[]) => void;

Add an array of allowed config properties.
Parameter metas
Array of objects to set as the allowed config properties.

method clear

static clear: () => Promise<void>;

Clear all the configured properties both local and global.

method getAllowedProperties

static getAllowedProperties: () => ConfigPropertyMeta[];

Returns an array of objects representing the allowed config properties.

method getFileName

static getFileName: () => string;

Returns the default file name for a config file.
**See** CONFIG_FILE_NAME

method getPropertyConfig

getPropertyConfig: (propertyName: string) => ConfigPropertyMeta;

Get an individual property config.
**Throws** *SfError{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
Parameter propertyName
The name of the property.

method getPropertyConfigMeta

static getPropertyConfigMeta: (
    propertyName: string
) => Nullable<ConfigPropertyMeta>;

method init

protected init: () => Promise<void>;

Initializer for supported config types.

method read

read: (force?: boolean) => Promise<ConfigProperties>;

Read, assign, and return the config contents.

method readSync

readSync: (force?: boolean) => ConfigProperties;

method set

set: (key: string, value: JsonPrimitive) => ConfigProperties;

Sets a value for a property.
**Throws** *SfError{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported. **Throws** *SfError{ name: 'InvalidConfigValueError' }* If the input validator fails.
Parameter key
The property to set.
Parameter value
The value of the property.

method unset

unset: (key: string) => boolean;

Unsets a value for a property.
**Throws** *SfError{ name: 'UnknownConfigKeyError' }* If the input validator fails.
Parameter key
The property to unset.

method update

static update: (
    isGlobal: boolean,
    propertyName: string,
    value?: AnyJson
) => Promise<ConfigContents>;

The value of a supported config property.
Parameter isGlobal
True for a global config. False for a local config.
Parameter propertyName
The name of the property to set.
Parameter value
The property value.

method write

write: (newContents?: ConfigProperties) => Promise<ConfigProperties>;

Writes Config properties taking into account encrypted properties.
Parameter newContents
The new Config value to persist.

method writeSync

writeSync: (newContents?: ConfigProperties) => ConfigProperties;

DO NOT CALL - The config file needs to encrypt values which can only be done asynchronously. Call SfdxConfig.write instead.
**Throws** *SfError{ name: 'InvalidWriteError' }* Always.
Parameter newContents
Contents to write

class ConfigAggregator

class ConfigAggregator extends AsyncOptionalCreatable<ConfigAggregator.Options> {}

Aggregate global and local project config files, as well as environment variables for config.json. The resolution happens in the following bottom-up order:
1. Environment variables (SF_LOG_LEVEL) 1. Workspace settings (<workspace-root>/.sf/config.json) 1. Global settings ($HOME/.sf/config.json)
Use ConfigAggregator.create to instantiate the aggregator.
const aggregator = await ConfigAggregator.create(); console.log(aggregator.getPropertyValue('target-org'));

constructor

constructor(options?: ConfigAggregator.Options);

**Do not directly construct instances of this class -- use ConfigAggregator.create instead.**

property encrypted

protected static encrypted: boolean;

property instance

protected static instance: AsyncOptionalCreatable;

method addAllowedProperties

addAllowedProperties: (
    configMetas: ConfigPropertyMeta | ConfigPropertyMeta[]
) => void;

Add an allowed config property.

method create

static create: <
    P extends ConfigAggregator.Options,
    T extends AsyncOptionalCreatable<P>
>(
    this: new (options?: P) => T,
    options?: P
) => Promise<T>;

method getAllowedProperties

protected getAllowedProperties: () => ConfigPropertyMeta[];

Get the allowed properties.

method getConfig

getConfig: () => JsonMap;

Get the resolved config object from the local, global and environment config instances.

method getConfigInfo

getConfigInfo: () => ConfigInfo[];

Get all resolved config property keys, values, locations, and paths.

> console.log(aggregator.getConfigInfo());
[
    { key: 'logLevel', val: 'INFO', location: 'Environment', path: '$SF_LOG_LEVEL'}
    { key: 'target-org', val: '<username>', location: 'Local', path: './.sf/config.json'}
]

method getEnvVars

getEnvVars: () => Dictionary<string>;

Get the config properties that are environment variables.

method getGlobalConfig

getGlobalConfig: () => Config;

Get the global config instance.

method getInfo

getInfo: (key: string, throwOnDeprecation?: boolean) => ConfigInfo;

Get a resolved config property.
Parameter key
The key of the property.
Parameter throwOnDeprecation
True, if you want an error throw when reading a deprecated config

method getLocalConfig

getLocalConfig: () => Config | undefined;

Get the local project config instance.

method getLocation

getLocation: (key: string) => Optional<ConfigAggregator.Location>;

Gets a resolved config property location.
For example, getLocation('logLevel') will return: 1. Location.GLOBAL if resolved to an environment variable. 1. Location.LOCAL if resolved to local project config. 1. Location.ENVIRONMENT if resolved to the global config.
Parameter key
The key of the property.

method getPath

getPath: (key: string) => Optional<string>;

Get a resolved file path or environment variable name of the property.
For example, getPath('logLevel') will return: 1. $SF_LOG_LEVEL if resolved to an environment variable. 1. ./.sf/config.json if resolved to the local config. 1. ~/.sf/config.json if resolved to the global config. 1. undefined, if not resolved.
**Note:** that the path returned may be the absolute path instead of relative paths such as ./ and ~/.
Parameter key
The key of the property.

method getPropertyMeta

getPropertyMeta: (key: string) => ConfigPropertyMeta;

Get a resolved config property meta.
**Throws** *SfError{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
Parameter key
The key of the property.

method getPropertyValue

getPropertyValue: <T extends AnyJson>(key: string) => Optional<T>;

Get a resolved config property.
**Throws** *SfError{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
Parameter key
The key of the property.

method getValue

static getValue: (key: string) => ConfigInfo;

Get the info for a given key. If the ConfigAggregator was not asynchronously created OR the ConfigAggregator.reload was not called, the config value may be encrypted.
Parameter key
The config key.

method init

init: () => Promise<void>;

Initialize this instances async dependencies.

method loadProperties

protected loadProperties: () => Promise<void>;

Loads all the properties and aggregates them according to location.

method reload

reload: () => Promise<ConfigAggregator>;

Re-read all property configurations from disk.

method setAllowedProperties

protected setAllowedProperties: (properties: ConfigPropertyMeta[]) => void;

Set the allowed properties.
Parameter properties
The properties to set.

class ConfigFile

class ConfigFile<
    T extends ConfigFile.Options = ConfigFile.Options,
    P extends ConfigContents = ConfigContents
> extends BaseConfigStore<T, P> {}

Represents a json config file used to manage settings and state. Global config files are stored in the home directory hidden state folder (.sfdx) and local config files are stored in the project path, either in the hidden state folder or wherever specified.
class MyConfig extends ConfigFile { public static getFileName(): string { return 'myConfigFilename.json'; } } const myConfig = await MyConfig.create({ isGlobal: true }); myConfig.set('mykey', 'myvalue'); await myConfig.write();

constructor

constructor(options?: ConfigFile.Options);

Create an instance of a config file without reading the file. Call read or readSync after creating the ConfigFile OR instantiate with ConfigFile.create instead.
Parameter options
The options for the class instance

property hasRead

protected hasRead: boolean;

property logger

protected logger: Logger;

method access

access: (perm?: number) => Promise<boolean>;

Determines if the config file is read/write accessible. Returns true if the user has capabilities specified by perm.
Parameter perm
The permission.
**See** https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback

method accessSync

accessSync: (perm?: number) => boolean;

Determines if the config file is read/write accessible. Returns true if the user has capabilities specified by perm.
Parameter perm
The permission.
**See** https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback

method exists

exists: () => Promise<boolean>;

Check to see if the config file exists. Returns true if the config file exists and has access, false otherwise.

method existsSync

existsSync: () => boolean;

Check to see if the config file exists. Returns true if the config file exists and has access, false otherwise.

method getDefaultOptions

static getDefaultOptions: (
    isGlobal?: boolean,
    filename?: string
) => ConfigFile.Options;

Returns the default options for the config file.
Parameter isGlobal
If the file should be stored globally or locally.
Parameter filename
The name of the config file.

method getFileName

static getFileName: () => string;

Returns the config's filename.

method getPath

getPath: () => string;

Returns the absolute path to the config file.
The first time getPath is called, the path is resolved and becomes immutable. This allows implementers to override options properties, like filePath, on the init method for async creation. If that is required for creation, the config files can not be synchronously created.

method init

protected init: () => Promise<void>;

Used to initialize asynchronous components.
**Throws** *Error{ code: 'ENOENT' }* If the ConfigFile.getFilename file is not found when options.throwOnNotFound is true.

method isGlobal

isGlobal: () => boolean;

Returns true if this config is using the global path, false otherwise.

method read

read: (throwOnNotFound?: boolean, force?: boolean) => Promise<P>;

Read the config file and set the config contents. Returns the config contents of the config file. As an optimization, files are only read once per process and updated in memory and via write(). To force a read from the filesystem pass force=true. **Throws** *SfError{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
Parameter throwOnNotFound
Optionally indicate if a throw should occur on file read.
Parameter force
Optionally force the file to be read from disk even when already read within the process.

method readSync

readSync: (throwOnNotFound?: boolean, force?: boolean) => P;

Read the config file and set the config contents. Returns the config contents of the config file. As an optimization, files are only read once per process and updated in memory and via write(). To force a read from the filesystem pass force=true. **Throws** *SfError{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
Parameter throwOnNotFound
Optionally indicate if a throw should occur on file read.
Parameter force
Optionally force the file to be read from disk even when already read within the process.

method resolveRootFolder

static resolveRootFolder: (isGlobal: boolean) => Promise<string>;

Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
Parameter isGlobal
True if the config should be global. False for local.

method resolveRootFolderSync

static resolveRootFolderSync: (isGlobal: boolean) => string;

Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
Parameter isGlobal
True if the config should be global. False for local.

method stat

stat: () => Promise<fsStats>;

Get the stats of the file. Returns the stats of the file.
fs.stat

method statSync

statSync: () => fsStats;

Get the stats of the file. Returns the stats of the file.
fs.stat

method unlink

unlink: () => Promise<void>;

Delete the config file if it exists.
**Throws** *Error{ name: 'TargetFileNotFound' }* If the ConfigFile.getFilename file is not found. fs.unlink

method unlinkSync

unlinkSync: () => void;

Delete the config file if it exists.
**Throws** *Error{ name: 'TargetFileNotFound' }* If the ConfigFile.getFilename file is not found. fs.unlink

method write

write: (newContents?: P) => Promise<P>;

Write the config file with new contents. If no new contents are provided it will write the existing config contents that were set from ConfigFile.read, or an empty file if ConfigFile.read was not called.
Parameter newContents
The new contents of the file.

method writeSync

writeSync: (newContents?: P) => P;

Write the config file with new contents. If no new contents are provided it will write the existing config contents that were set from ConfigFile.read, or an empty file if ConfigFile.read was not called.
Parameter newContents
The new contents of the file.

class Connection

class Connection<S extends Schema = Schema> extends JSForceConnection<S> {}

Handles connections and requests to Salesforce Orgs.

// Uses latest API version
const connection = await Connection.create({
  authInfo: await AuthInfo.create({ username: 'myAdminUsername' })
});
connection.query('SELECT Name from Account');

// Use different API version
connection.setApiVersion("42.0");
connection.query('SELECT Name from Account');

constructor

constructor(options: Connection.Options<S>);

Constructor **Do not directly construct instances of this class -- use Connection.create instead.**
Parameter options
The options for the class instance.

property tooling

readonly tooling: Tooling<S>;

Tooling api reference.

method autoFetchQuery

autoFetchQuery: <T extends Schema = S>(
    soql: string,
    queryOptions?: Partial<QueryOptions & { tooling: boolean }>
) => Promise<QueryResult<T>>;

Executes a query and auto-fetches (i.e., "queryMore") all results. This is especially useful with large query result sizes, such as over 2000 records. The default maximum fetch size is 10,000 records. Modify this via the options argument.
Parameter soql
The SOQL string.
Parameter queryOptions
The query options. NOTE: the autoFetch option will always be true.

method baseUrl

baseUrl: () => string;

The Force API base url for the instance.

method create

static create: <S extends Schema>(
    this: new (options: Connection.Options<S>) => Connection<S>,
    options: Connection.Options<S>
) => Promise<Connection<S>>;

Creates an instance of a Connection. Performs additional async initializations.
Parameter options
Constructor options.

method deploy

deploy: (
    zipInput: Buffer,
    options: DeployOptionsWithRest
) => Promise<DeployResultLocator<AsyncResult & Schema>>;

deploy a zipped buffer from the SDRL with REST or SOAP
Parameter zipInput
data to deploy
Parameter options
JSForce deploy options + a boolean for rest

method deployRecentValidation

deployRecentValidation: (
    options: recentValidationOptions
) => Promise<JsonCollection>;

Will deploy a recently validated deploy request - directly calling jsforce now that this is supported. WARNING: will always return a string from jsforce, the type is JsonCollection to support backwards compatibility
Parameter
options.id = the deploy ID that's been validated already from a previous checkOnly deploy request
Parameter
options.rest = a boolean whether or not to use the REST API
Deprecated
use Connection.metadata#deployRecentValidation instead - the jsforce implementation, instead of this wrapper

method getApiVersion

getApiVersion: () => string;

Get the API version used for all connection requests.

method getAuthInfo

getAuthInfo: () => AuthInfo;

Getter for AuthInfo.

method getAuthInfoFields

getAuthInfoFields: () => AuthFields;

Getter for the AuthInfo fields.

method getConnectionOptions

getConnectionOptions: () => AuthFields;

Getter for the auth fields.

method getUsername

getUsername: () => Optional<string>;

Getter for the username of the Salesforce Org.

method init

init: () => Promise<void>;

Async initializer.

method isResolvable

isResolvable: () => Promise<boolean>;

Verify that instance has a reachable DNS entry, otherwise will throw error

method isUsingAccessToken

isUsingAccessToken: () => boolean;

Returns true if this connection is using access token auth.

method normalizeUrl

normalizeUrl: (url: string) => string;

Normalize a Salesforce url to include a instance information.
Parameter url
Partial url.

method refreshAuth

refreshAuth: () => Promise<void>;

Executes a get request on the baseUrl to force an auth refresh Useful for the raw methods (request, requestRaw) that use the accessToken directly and don't handle refreshes

method request

request: <R = unknown>(
    request: string | HttpRequest,
    options?: JsonMap
) => StreamPromise<R>;

Send REST API request with given HTTP request info, with connected session information and SFDX headers.
Parameter request
HTTP request object or URL to GET request.
Parameter options
HTTP API request options.

method retrieveMaxApiVersion

retrieveMaxApiVersion: () => Promise<string>;

Retrieves the highest api version that is supported by the target server instance.

method setApiVersion

setApiVersion: (version: string) => void;

Set the API version for all connection requests.
**Throws** *SfError{ name: 'IncorrectAPIVersionError' }* Incorrect API version.
Parameter version
The API version.

method singleRecordQuery

singleRecordQuery: <T extends Record>(
    soql: string,
    options?: SingleRecordQueryOptions
) => Promise<T>;

Executes a query using either standard REST or Tooling API, returning a single record. Will throw if either zero records are found OR multiple records are found.
Parameter soql
The SOQL string.
Parameter options
The query options.

method useLatestApiVersion

useLatestApiVersion: () => Promise<void>;

Use the latest API version available on this.instanceUrl.

class DefaultUserFields

class DefaultUserFields extends AsyncCreatable<DefaultUserFields.Options> {}

Provides a default set of fields values that can be used to create a user. This is handy for software development purposes.

const connection: Connection = await Connection.create({
  authInfo: await AuthInfo.create({ username: 'user@example.com' })
});
const org: Org = await Org.create({ connection });
const options: DefaultUserFields.Options = {
  templateUser: org.getUsername()
};
const fields = (await DefaultUserFields.create(options)).getFields();

constructor

constructor(options: DefaultUserFields.Options);

method getFields

getFields: () => UserFields;

Get user fields.

method init

protected init: () => Promise<void>;

Initialize asynchronous components.

class DeviceOauthService

class DeviceOauthService extends AsyncCreatable<OAuth2Config> {}

Handles device based login flows

Usage:

const oauthConfig = {
  loginUrl: this.flags.instanceurl,
  clientId: this.flags.clientid,
};
const deviceOauthService = await DeviceOauthService.create(oauthConfig);
const loginData = await deviceOauthService.requestDeviceLogin();
console.log(loginData);
const approval = await deviceOauthService.awaitDeviceApproval(loginData);
const authInfo = await deviceOauthService.authorizeAndSave(approval);

constructor

constructor(options: OAuth2Config);

property GRANT_TYPE

static GRANT_TYPE: string;

property RESPONSE_TYPE

static RESPONSE_TYPE: string;

property SCOPE

static SCOPE: string;

method authorizeAndSave

authorizeAndSave: (approval: DeviceCodePollingResponse) => Promise<AuthInfo>;

Creates and saves new AuthInfo
Returns
{Promise}

method awaitDeviceApproval

awaitDeviceApproval: (
    loginData: DeviceCodeResponse
) => Promise<Nullable<DeviceCodePollingResponse>>;

Polls the server until successful response OR max attempts have been made
Returns
{Promise<Nullable>}

method init

protected init: () => Promise<void>;

method requestDeviceLogin

requestDeviceLogin: () => Promise<DeviceCodeResponse>;

Begin the authorization flow by requesting the login
Returns
{Promise}

class EnvVars

class EnvVars extends Env {}

constructor

constructor(env?: NodeJS.ProcessEnv);

method asDictionary

asDictionary: () => Dictionary<unknown>;

method asMap

asMap: () => Map<string, string>;

method getPropertyFromEnv

getPropertyFromEnv: <T>(property: string, prefix?: string) => Nullable<T>;

method propertyToEnvName

static propertyToEnvName: (property: string, prefix?: string) => string;

class Global

class Global {}

Global constants, methods, and configuration.

property DIR

static readonly DIR: string;

The full system path to the preferred global state folder

property LOG_FILE_PATH

static readonly LOG_FILE_PATH: string;

The full system path to the global log file.

property SF_DIR

static readonly SF_DIR: string;

The full system path to the global sf state folder.
**See** Global.SF_STATE_FOLDER

property SF_STATE_FOLDER

static readonly SF_STATE_FOLDER: string;

The global folder in which sf state is stored.

property SFDX_DIR

static readonly SFDX_DIR: string;

The full system path to the global sfdx state folder.
**See** Global.SFDX_STATE_FOLDER

property SFDX_INTEROPERABILITY

static SFDX_INTEROPERABILITY: boolean;

Enable interoperability between .sfdx and .sf.
When @salesforce/core@v2 is deprecated and no longer used, this can be removed.

property SFDX_STATE_FOLDER

static readonly SFDX_STATE_FOLDER: string;

The global folder in which sfdx state is stored.

property STATE_FOLDER

static readonly STATE_FOLDER: string;

The preferred global folder in which state is stored.

method createDir

static createDir: (dirPath?: string) => Promise<void>;

Creates a directory within Global.SFDX_DIR, or Global.SFDX_DIR itself if the dirPath param is not provided. This is resolved or rejected when the directory creation operation has completed.
Parameter dirPath
The directory path to be created within Global.SFDX_DIR.

method getEnvironmentMode

static getEnvironmentMode: () => Mode;

Gets the current mode environment variable as a Mode instance.

console.log(Global.getEnvironmentMode() === Mode.PRODUCTION);

class Lifecycle

class Lifecycle {}

An asynchronous event listener and emitter that follows the singleton pattern. The singleton pattern allows lifecycle events to be emitted from deep within a library and still be consumed by any other library or tool. It allows other developers to react to certain situations or events in your library without them having to manually call the method themselves.
An example might be transforming metadata before it is deployed to an environment. As long as an event was emitted from the deploy library and you were listening on that event in the same process, you could transform the metadata before the deploy regardless of where in the code that metadata was initiated.
Example 1
// Listen for an event in a plugin hook Lifecycle.getInstance().on('deploy-metadata', transformMetadata) // Deep in the deploy code, fire the event for all libraries and plugins to hear. Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed); // if you don't need to await anything use `void Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed)` ;

property telemetryEventName

static readonly telemetryEventName: string;

property warningEventName

static readonly warningEventName: string;

method emit

emit: <T = AnyJson>(eventName: string, data: T) => Promise<void>;

Emit a given event, causing all callback functions to be run in the order they were registered
Parameter eventName
The name of the event to emit
Parameter data
The argument to be passed to the callback function

method emitTelemetry

emitTelemetry: (data: AnyJson) => Promise<void>;

Emit a telemetry event, causing all callback functions to be run in the order they were registered
Parameter data
The data to emit

method emitWarning

emitWarning: (warning: string) => Promise<void>;

Emit a warning event, causing all callback functions to be run in the order they were registered
Parameter data
The warning (string) to emit

method getInstance

static getInstance: () => Lifecycle;

Retrieve the singleton instance of this class so that all listeners and emitters can interact from any library or tool

method getListeners

getListeners: (eventName: string) => callback[];

Get an array of listeners (callback functions) for a given event
Parameter eventName
The name of the event to get listeners of

method on

on: <T = AnyJson>(eventName: string, cb: (data: T) => Promise<void>) => void;

Create a new listener for a given event
Parameter eventName
The name of the event that is being listened for
Parameter cb
The callback function to run when the event is emitted

method onTelemetry

onTelemetry: (cb: (data: Record<string, unknown>) => Promise<void>) => void;

Create a listener for the telemetry event
Parameter cb
The callback function to run when the event is emitted

method onWarning

onWarning: (cb: (warning: string) => Promise<void>) => void;

Create a listener for the warning event
Parameter cb
The callback function to run when the event is emitted

method removeAllListeners

removeAllListeners: (eventName: string) => void;

Remove all listeners for a given event
Parameter eventName
The name of the event to remove listeners of

method staticVersion

static staticVersion: () => string;

return the package.json version of the sfdx-core library.

method version

version: () => string;

return the package.json version of the sfdx-core library.

class Logger

class Logger {}

A logging abstraction powered by Bunyan that provides both a default logger configuration that will log to sfdx.log, and a way to create custom loggers based on the same foundation.

// Gets the root sfdx logger
const logger = await Logger.root();

// Creates a child logger of the root sfdx logger with custom fields applied
const childLogger = await Logger.child('myRootChild', {tag: 'value'});

// Creates a custom logger unaffiliated with the root logger
const myCustomLogger = new Logger('myCustomLogger');

// Creates a child of a custom logger unaffiliated with the root logger with custom fields applied
const myCustomChildLogger = myCustomLogger.child('myCustomChild', {tag: 'value'});

**See** https://github.com/forcedotcom/node-bunyan

**See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm

constructor

constructor(optionsOrName: string | LoggerOptions);

Constructs a new Logger.
Parameter optionsOrName
A set of LoggerOptions or name to use with the default options.
**Throws** *SfError{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root Logger.

property debugEnabled

debugEnabled: boolean;

Whether debug is enabled for this Logger.

property DEFAULT_LEVEL

static readonly DEFAULT_LEVEL: number;

The default LoggerLevel when constructing new Logger instances.

property LEVEL_NAMES

static readonly LEVEL_NAMES: string[];

A list of all lower case LoggerLevel names.
**See** LoggerLevel

property logRotationCount

readonly logRotationCount: number;

The number of backup rotated log files to keep. Example: '3' will have the base sf.log file, and the past 3 (period) log files. See 'count' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file

property logRotationPeriod

readonly logRotationPeriod: string;

The default rotation period for logs. Example '1d' will rotate logs daily (at midnight). See 'period' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file

property ROOT_NAME

static readonly ROOT_NAME: string;

The name of the root sfdx Logger.

method addField

addField: (name: string, value: FieldValue) => Logger;

Add a field to all log lines for this logger. For convenience this object is returned.
Parameter name
The name of the field to add.
Parameter value
The value of the field to be logged.

method addFilter

addFilter: (filter: (...args: unknown[]) => unknown) => void;

Adds a filter to be applied to all logged messages.
Parameter filter
A function with signature (...args: any[]) => any[] that transforms log message arguments.

method addLogFileStream

addLogFileStream: (logFile: string) => Promise<void>;

Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
Parameter logFile
The path to the log file. If it doesn't exist it will be created.

method addLogFileStreamSync

addLogFileStreamSync: (logFile: string) => void;

Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
Parameter logFile
The path to the log file. If it doesn't exist it will be created.

method addStream

addStream: (stream: LoggerStream, defaultLevel?: LoggerLevelValue) => void;

Adds a stream.
Parameter stream
The stream configuration to add.
Parameter defaultLevel
The default level of the stream.

method child

static child: (name: string, fields?: Fields) => Promise<Logger>;

Create a child of the root logger, inheriting this instance's configuration such as level, streams, etc.
Parameter name
The name of the child logger.
Parameter fields
Additional fields included in all log lines.
Create a child logger, typically to add a few log record fields. For convenience this object is returned.
Parameter name
The name of the child logger that is emitted w/ log line as log:<name>.
Parameter fields
Additional fields included in all log lines for the child logger.

method childFromRoot

static childFromRoot: (name: string, fields?: Fields) => Logger;

Create a child of the root logger, inheriting this instance's configuration such as level, streams, etc.
Parameter name
The name of the child logger.
Parameter fields
Additional fields included in all log lines.

method close

close: (fn?: (stream: LoggerStream) => void) => void;

Close the logger, including any streams, and remove all listeners.
Parameter fn
A function with signature (stream: LoggerStream) => void to call for each stream with the stream as an arg.

method debug

debug: (...args: unknown[]) => Logger;

Logs at debug level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

method debugCallback

debugCallback: (cb: () => unknown[] | string) => void;

Logs at debug level with filtering applied.
Parameter cb
A callback that returns on array objects to be logged.

method destroyRoot

static destroyRoot: () => void;

Destroys the root Logger.

method enableDEBUG

enableDEBUG: () => void;

Enables logging to stdout when the DEBUG environment variable is used. It uses the logger name as the debug name, so you can do DEBUG= to filter the results to your logger.

method error

error: (...args: unknown[]) => Logger;

Logs at error level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

method fatal

fatal: (...args: unknown[]) => Logger;

Logs at fatal level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

method getBufferedRecords

getBufferedRecords: () => LogLine[];

Gets an array of log line objects. Each element is an object that corresponds to a log line.

method getBunyanLogger

getBunyanLogger: () => any;

Gets the underlying Bunyan logger.

method getLevel

getLevel: () => LoggerLevelValue;

Gets the current level of this logger.

method getLevelByName

static getLevelByName: (levelName: string) => LoggerLevelValue;

Gets a numeric LoggerLevel value by string name.
Parameter levelName
The level name to convert to a LoggerLevel enum value.
**Throws** *SfError{ name: 'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid LoggerLevel value.
See Also
- LoggerLevel

method getName

getName: () => string;

Gets the name of this logger.

method getRoot

static getRoot: () => Logger;

Gets the root logger with the default level, file stream, and DEBUG enabled.

method info

info: (...args: unknown[]) => Logger;

Logs at info level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

method readLogContentsAsText

readLogContentsAsText: () => string;

Reads a text blob of all the log lines contained in memory or the log file.

method root

static root: () => Promise<Logger>;

Gets the root logger with the default level, file stream, and DEBUG enabled.

method setLevel

setLevel: (level?: LoggerLevelValue) => Logger;

Set the logging level of all streams for this logger. If a specific level is not provided, this method will attempt to read it from the environment variable SFDX_LOG_LEVEL, and if not found, Logger.DEFAULT_LOG_LEVEL will be used instead. For convenience this object is returned.
Parameter level
The logger level.
**Throws** *SfError{ name: 'UnrecognizedLoggerLevelNameError' }* A value of level read from SFDX_LOG_LEVEL was invalid.
// Sets the level from the environment or default value logger.setLevel() // Set the level from the INFO enum logger.setLevel(LoggerLevel.INFO) // Sets the level case-insensitively from a string value logger.setLevel(Logger.getLevelByName('info'))

method shouldLog

shouldLog: (level: LoggerLevelValue) => boolean;

Compares the requested log level with the current log level. Returns true if the requested log level is greater than or equal to the current log level.
Parameter level
The requested log level to compare against the currently set log level.

method trace

trace: (...args: any[]) => Logger;

Logs at trace level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

method useMemoryLogging

useMemoryLogging: () => Logger;

Use in-memory logging for this logger instance instead of any parent streams. Useful for testing. For convenience this object is returned.
**WARNING: This cannot be undone for this logger instance.**

method warn

warn: (...args: unknown[]) => Logger;

Logs at warn level with filtering applied. For convenience this object is returned.
Parameter args
Any number of arguments to be logged.

class Messages

class Messages<T extends string> {}

The core message framework manages messages and allows them to be accessible by all plugins and consumers of sfdx-core. It is set up to handle localization down the road at no additional effort to the consumer. Messages can be used for anything from user output (like the console), to error messages, to returned data from a method.
Messages are loaded from loader functions. The loader functions will only run when a message is required. This prevents all messages from being loaded into memory at application startup. The functions can load from memory, a file, or a server.
In the beginning of your app or file, add the loader functions to be used later. If using json or js files in a root messages directory (<moduleRoot>/messages), load the entire directory automatically with Messages.importMessagesDirectory. Message files must be the following formates.
A .json file:
{ "msgKey": "A message displayed in the user", "msgGroup": { "anotherMsgKey": "Another message displayed to the user" }, "listOfMessage": ["message1", "message2"] }
A .js file:
module.exports = { msgKey: 'A message displayed in the user', msgGroup: { anotherMsgKey: 'Another message displayed to the user' }, listOfMessage: ['message1', 'message2'] }
A .md file:
# msgKey A message displayed in the user # msgGroup.anotherMsgKey Another message displayed to the user # listOfMessage - message1 - message2
The values support [util.format](https://nodejs.org/api/util.html#util_util_format_format_args) style strings that apply the tokens passed into Message.getMessage
**Note:** When running unit tests individually, you may see errors that the messages aren't found. This is because index.js isn't loaded when tests run like they are when the package is required. To allow tests to run, import the message directory in each test (it will only do it once) or load the message file the test depends on individually.
// Create loader functions for all files in the messages directory Messages.importMessagesDirectory(__dirname); // Now you can use the messages from anywhere in your code or file. // If using importMessageDirectory, the bundle name is the file name. const messages: Messages = Messages.load(packageName, bundleName); // Messages now contains all the message in the bundleName file. messages.getMessage('authInfoCreationError');

constructor

constructor(bundleName: string, locale: string, messages: StoredMessageMap);

Create a new messages bundle.
**Note:** Use {Messages.load} unless you are writing your own loader function.
Parameter bundleName
The bundle name.
Parameter locale
The locale.
Parameter messages
The messages. Can not be modified once created.

property bundleName

readonly bundleName: string;

The bundle name.

property locale

readonly locale: string;

The locale of the messages in this bundle.

property readFile

static readFile: (filePath: string) => AnyJson;

Internal readFile. Exposed for unit testing. Do not use util/fs.readFile as messages.js should have no internal dependencies.
Parameter filePath
read file target.

method createError

createError: (
    key: T,
    tokens?: Tokens,
    actionTokens?: Tokens,
    exitCodeOrCause?: number | Error,
    cause?: Error
) => SfError;

Convenience method to create errors using message labels.
error.name will be the upper-cased key, remove prefixed error. and will always end in Error. error.actions will be loaded using ${key}.actions if available.
Parameter key
The key of the error message.
Parameter tokens
The error message tokens.
Parameter actionTokens
The action messages tokens.
Parameter exitCodeOrCause
The exit code which will be used by SfdxCommand or the underlying error that caused this error to be raised.
Parameter cause
The underlying error that caused this error to be raised.

method createErrorButPreserveName

createErrorButPreserveName: (
    key: T,
    tokens?: Tokens,
    actionTokens?: Tokens,
    exitCodeOrCause?: number | Error,
    cause?: Error
) => SfError;

SfError wants error names to end with the suffix Error. Use this to create errors while preserving their existing name (for compatibility reasons).
Parameter key
The key of the error message.
Parameter tokens
The error message tokens.
Parameter actionTokens
The action messages tokens.
Parameter exitCodeOrCause
The exit code which will be used by SfdxCommand or the underlying error that caused this error to be raised.
Parameter cause
The underlying error that caused this error to be raised.
Deprecated
Use createError instead unless you need to preserver the error name to avoid breaking changes. error.name will be the upper-cased key, remove prefixed error.. error.actions will be loaded using ${key}.actions if available.

method createInfo

createInfo: (
    key: T,
    tokens?: Tokens,
    actionTokens?: Tokens
) => StructuredMessage;

Convenience method to create info using message labels.
info.name will be the upper-cased key, remove prefixed info. and will always end in Info. info.actions will be loaded using ${key}.actions if available.
Parameter key
The key of the warning message.
Parameter tokens
The warning message tokens.
Parameter actionTokens
The action messages tokens.

method createWarning

createWarning: (
    key: T,
    tokens?: Tokens,
    actionTokens?: Tokens
) => StructuredMessage;

Convenience method to create warning using message labels.
warning.name will be the upper-cased key, remove prefixed warning. and will always end in Warning. warning.actions will be loaded using ${key}.actions if available.
Parameter key
The key of the warning message.
Parameter tokens
The warning message tokens.
Parameter actionTokens
The action messages tokens.

method generateFileLoaderFunction

static generateFileLoaderFunction: (
    bundleName: string,
    filePath: string
) => LoaderFunction<string>;

Generate a file loading function. Use Messages.importMessageFile unless overriding the bundleName is required, then manually pass the loader function to Messages.setLoaderFunction.
Parameter bundleName
The name of the bundle.
Parameter filePath
The messages file path.

method getLocale

static getLocale: () => string;

Get the locale. This will always return 'en_US' but will return the machine's locale in the future.

method getMessage

getMessage: (key: T, tokens?: Tokens) => string;

Get a message using a message key and use the tokens as values for tokenization.
If the key happens to be an array of messages, it will combine with OS.EOL.
Parameter key
The key of the message.
Parameter tokens
The values to substitute in the message.
**See** https://nodejs.org/api/util.html#util_util_format_format_args

method getMessages

getMessages: (key: T, tokens?: Tokens) => string[];

Get messages using a message key and use the tokens as values for tokenization.
This will return all messages if the key is an array in the messages file.
{ "myKey": [ "message1", "message2" ] }
# myKey * message1 * message2
Parameter key
The key of the messages.
Parameter tokens
The values to substitute in the message.
**See** https://nodejs.org/api/util.html#util_util_format_format_args

method importMessageFile

static importMessageFile: (packageName: string, filePath: string) => void;

Add a single message file to the list of loading functions using the file name as the bundle name. The loader will only be added if the bundle name is not already taken.
Parameter packageName
The npm package name.
Parameter filePath
The path of the file.

method importMessagesDirectory

static importMessagesDirectory: (
    moduleDirectoryPath: string,
    truncateToProjectPath?: boolean,
    packageName?: string
) => void;

Import all json and js files in a messages directory. Use the file name as the bundle key when Messages.load is called. By default, we're assuming the moduleDirectoryPart is a typescript project and will truncate to root path (where the package.json file is). If your messages directory is in another spot or you are not using typescript, pass in false for truncateToProjectPath.
// e.g. If your message directory is in the project root, you would do: Messages.importMessagesDirectory(__dirname);
Parameter moduleDirectoryPath
The path to load the messages folder.
Parameter truncateToProjectPath
Will look for the messages directory in the project root (where the package.json file is located). i.e., the module is typescript and the messages folder is in the top level of the module directory.
Parameter packageName
The npm package name. Figured out from the root directory's package.json.

method isCached

static isCached: (packageName: string, bundleName: string) => boolean;

Check if a bundle already been loaded.
Parameter packageName
The npm package name.
Parameter bundleName
The bundle name.

method load

static load: <T extends string>(
    packageName: string,
    bundleName: string,
    keys: [T, ...T[]]
) => Messages<T>;

Load messages for a given package and bundle. If the bundle is not already cached, use the loader function created from Messages.setLoaderFunction or Messages.importMessagesDirectory.
The message keys that will be used must be passed in for validation. This prevents runtime errors if messages are used but not defined.
**NOTE: This should be defined at the top of the file so validation is done at load time rather than runtime.**
Messages.importMessagesDirectory(__dirname); const messages = Messages.load('packageName', 'bundleName', [ 'messageKey1', 'messageKey2', ]);
Parameter packageName
The name of the npm package.
Parameter bundleName
The name of the bundle to load.
Parameter keys
The message keys that will be used.

method loadMessages

static loadMessages: (
    packageName: string,
    bundleName: string
) => Messages<string>;

Load messages for a given package and bundle. If the bundle is not already cached, use the loader function created from Messages.setLoaderFunction or Messages.importMessagesDirectory.
**NOTE: Use Messages.load instead for safe message validation and usage.**
Messages.importMessagesDirectory(__dirname); const messages = Messages.load('packageName', 'bundleName');
Parameter packageName
The name of the npm package.
Parameter bundleName
The name of the bundle to load.

method setLoaderFunction

static setLoaderFunction: (
    packageName: string,
    bundle: string,
    loader: LoaderFunction<string>
) => void;

Set a custom loader function for a package and bundle that will be called on Messages.load.
Parameter packageName
The npm package name.
Parameter bundle
The name of the bundle.
Parameter loader
The loader function.

class MyDomainResolver

class MyDomainResolver extends AsyncOptionalCreatable<MyDomainResolver.Options> {}

A class used to resolve MyDomains. After a ScratchOrg is created its host name my not be propagated to the Salesforce DNS service. This service is not exclusive to Salesforce My Domain URL and could be used for any hostname.

(async () => {
 const options: MyDomainResolver.Options = {
     url: new URL('http://mydomain.salesforce.com'),
     timeout: Duration.minutes(5),
     frequency: Duration.seconds(10)
 };
 const resolver: MyDomainResolver = await MyDomainResolver.create(options);
 const ipAddress: AnyJson = await resolver.resolve();
 console.log(`Successfully resolved host: ${options.url} to address: ${ipAddress}`);
})();

constructor

constructor(options?: MyDomainResolver.Options);

Constructor **Do not directly construct instances of this class -- use MyDomainResolver.create instead.**
Parameter options
The options for the class instance

property DEFAULT_DOMAIN

static DEFAULT_DOMAIN: URL;

method getCnames

getCnames: () => Promise<string[]>;

method getFrequency

getFrequency: () => Duration;

method getTimeout

getTimeout: () => Duration;

method init

protected init: () => Promise<void>;

Used to initialize asynchronous components.

method resolve

resolve: () => Promise<string>;

Method that performs the dns lookup of the host. If the lookup fails the internal polling client will try again given the optional interval. Returns the resolved ip address.
If SFDX_DISABLE_DNS_CHECK environment variable is set to true, it will immediately return the host without executing the dns loookup.

class Org

class Org extends AsyncOptionalCreatable<Org.Options> {}

Provides a way to manage a locally authenticated Org.

**See** AuthInfo

**See** Connection

**See** Aliases

**See** Config

// Email username
const org1: Org = await Org.create({ aliasOrUsername: 'foo@example.com' });
// The target-org config property
const org2: Org = await Org.create();
// Full Connection
const org3: Org = await Org.create({
  connection: await Connection.create({
    authInfo: await AuthInfo.create({ username: 'username' })
  })
});

**See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_usernames_orgs.htm

constructor

constructor(options?: Org.Options);

method addUsername

addUsername: (auth: AuthInfo | string) => Promise<Org>;

Adds a username to the user config for this org. For convenience this object is returned.

const org: Org = await Org.create({
  connection: await Connection.create({
    authInfo: await AuthInfo.create('foo@example.com')
  })
});
const userAuth: AuthInfo = await AuthInfo.create({
  username: 'bar@example.com'
});
await org.addUsername(userAuth);

Parameter auth

The AuthInfo for the username to add.

method checkScratchOrg

checkScratchOrg: (
    devHubUsernameOrAlias?: string
) => Promise<Partial<AuthFields>>;

Check that this org is a scratch org by asking the dev hub if it knows about it.
**Throws** *SfError{ name: 'NotADevHubError' }* Not a Dev Hub.
**Throws** *SfError{ name: 'NoResultsError' }* No results.
Parameter devHubUsernameOrAlias
The username or alias of the dev hub org.

method cleanLocalOrgData

cleanLocalOrgData: (
    orgDataPath?: string,
    throwWhenRemoveFails?: boolean
) => Promise<void>;

Clean all data files in the org's data path. Usually /.sfdx/orgs/.
Parameter orgDataPath
A relative path other than "orgs/".
Parameter throwWhenRemoveFails
Should the remove org operations throw an error on failure?

method cloneSandbox

cloneSandbox: (
    sandboxReq: SandboxRequest,
    sourceSandboxName: string,
    options: { wait?: Duration; interval?: Duration }
) => Promise<SandboxProcessObject>;

Parameter sandboxReq
SandboxRequest options to create the sandbox with
Parameter sourceSandboxName
the name of the sandbox that your new sandbox will be based on
Parameter options
Wait: The amount of time to wait before timing out, defaults to 0, Interval: The time interval between polling defaults to 30 seconds
Returns
{SandboxProcessObject} the newly created sandbox process object

method createSandbox

createSandbox: (
    sandboxReq: SandboxRequest,
    options?: { wait?: Duration; interval?: Duration; async?: boolean }
) => Promise<SandboxProcessObject>;

create a sandbox from a production org 'this' needs to be a production org with sandbox licenses available
Parameter sandboxReq
SandboxRequest options to create the sandbox with
Parameter options
Wait: The amount of time to wait before timing out, Interval: The time interval between polling

method delete

delete: () => Promise<void>;

Will delete 'this' instance remotely and any files locally

method deleteFrom

deleteFrom: (controllingOrg: string | Org) => Promise<void>;

Will delete 'this' instance remotely and any files locally
Parameter controllingOrg
username or Org that 'this.devhub' or 'this.production' refers to. AKA a DevHub for a scratch org, or a Production Org for a sandbox

method determineIfDevHubOrg

determineIfDevHubOrg: (forceServerCheck?: boolean) => Promise<boolean>;

Returns true if the org is a Dev Hub.
Use a cached value. If the cached value is not set, then check access to the ScratchOrgInfo object to determine if the org is a dev hub.
Parameter forceServerCheck
Ignore the cached value and go straight to the server which will be required if the org flips on the dev hub after the value is already cached locally.

method determineIfSandbox

determineIfSandbox: () => Promise<boolean>;

Returns true if the org is a sandbox.
Use a cached value. If the cached value is not set, then check Organization.IsSandbox == true && Organization.TrialExpirationDate == null using Org.retrieveOrganizationInformation.

method determineIfScratch

determineIfScratch: () => Promise<boolean>;

Returns true if the org is a scratch org.
Use a cached value. If the cached value is not set, then check Organization.IsSandbox == true && Organization.TrialExpirationDate != null using Org.retrieveOrganizationInformation.

method getConfigAggregator

getConfigAggregator: () => ConfigAggregator;

Returns for the config aggregator.

method getConnection

getConnection: (apiVersion?: string) => Connection;

Returns the JSForce connection for the org. side effect: If you pass it an apiVersion, it will set it on the Org so that future calls to getConnection() will also use that version.
Parameter apiVersion
The API version to use for the connection.

method getDefaultOptions

protected getDefaultOptions: () => Org.Options;

**Throws** *SfError{ name: 'NotSupportedError' }* Throws an unsupported error.

method getDevHubOrg

getDevHubOrg: () => Promise<Optional<Org>>;

Returns the Org object or null if this org is not affiliated with a Dev Hub (according to the local config).

method getField

getField: <T = AnyJson>(key: Org.Fields) => T;

Returns an org field. Returns undefined if the field is not set or invalid.

method getFields

getFields: (keys: Org.Fields[]) => JsonMap;

Returns a map of requested fields.

method getOrgId

getOrgId: () => string;

Returns the orgId for this org.

method getSandboxConfig

getSandboxConfig: (orgId: string) => Promise<Nullable<SandboxFields>>;

get the sandbox config for the given orgId
Parameter orgId
orgId of the sandbox

method getUsername

getUsername: () => Optional<string>;

Returns the admin username used to create the org.

method init

protected init: () => Promise<void>;

Initialize async components.

method isDevHubOrg

isDevHubOrg: () => boolean;

Returns true if the org is a Dev Hub.
**Note** This relies on a cached value in the auth file. If that property is not cached, this method will **always return false even if the org is a dev hub**. If you need accuracy, use the Org.determineIfDevHubOrg method.

method isSandbox

isSandbox: () => Promise<boolean>;

Check if org is a sandbox org by checking its SandboxOrgConfig.

method isScratch

isScratch: () => boolean;

Returns true if the org is a scratch org.
**Note** This relies on a cached value in the auth file. If that property is not cached, this method will **always return false even if the org is a scratch org**. If you need accuracy, use the Org.determineIfScratch method.

method querySandboxProcessById

querySandboxProcessById: (id: string) => Promise<SandboxProcessObject>;

query SandboxProcess via Id
Parameter id
SandboxProcessId to query for

method querySandboxProcessBySandboxInfoId

querySandboxProcessBySandboxInfoId: (
    id: string
) => Promise<SandboxProcessObject>;

query SandboxProcess via SandboxInfoId
Parameter id
SandboxInfoId to query for

method querySandboxProcessBySandboxName

querySandboxProcessBySandboxName: (
    name: string
) => Promise<SandboxProcessObject>;

query SandboxProcess via sandbox name
Parameter name
SandboxName to query for

method readUserAuthFiles

readUserAuthFiles: () => Promise<AuthInfo[]>;

Reads and returns the content of all user auth files for this org as an array.

method refreshAuth

refreshAuth: () => Promise<void>;

Refreshes the auth for this org's instance by calling HTTP GET on the baseUrl of the connection object.

method remove

remove: (throwWhenRemoveFails?: boolean) => Promise<void>;

Cleans up all org related artifacts including users, sandbox config (if a sandbox), source tracking files, and auth file.
Parameter throwWhenRemoveFails
Determines if the call should throw an error or fail silently.

method removeUsername

removeUsername: (auth: AuthInfo | string) => Promise<Org>;

Removes a username from the user config for this object. For convenience this object is returned.
**Throws** *SfError{ name: 'MissingAuthInfoError' }* Auth info is missing.
Parameter auth
The AuthInfo containing the username to remove.

method resumeSandbox

resumeSandbox: (
    resumeSandboxRequest: ResumeSandboxRequest,
    options?: { wait?: Duration; interval?: Duration; async?: boolean }
) => Promise<SandboxProcessObject>;

resume a sandbox creation from a production org 'this' needs to be a production org with sandbox licenses available
Parameter resumeSandboxRequest
SandboxRequest options to create the sandbox with
Parameter options
Wait: The amount of time to wait (default: 30 minutes) before timing out, Interval: The time interval (default: 30 seconds) between polling

method retrieveMaxApiVersion

retrieveMaxApiVersion: () => Promise<string>;

Retrieves the highest api version that is supported by the target server instance. If the apiVersion configured for Sfdx is greater than the one returned in this call an api version mismatch occurs. In the case of the CLI that results in a warning.

method retrieveOrganizationInformation

retrieveOrganizationInformation: () => Promise<OrganizationInformation>;

Retrieve a handful of fields from the Organization table in Salesforce. If this does not have the data you need, just use Connection.singleRecordQuery with SELECT <needed fields> FROM Organization.
Returns
org information

method retrieveOrgUsersConfig

retrieveOrgUsersConfig: () => Promise<OrgUsersConfig>;

method sandboxStatus

sandboxStatus: (
    sandboxname: string,
    options: { wait?: Duration; interval?: Duration }
) => Promise<SandboxProcessObject>;

Reports sandbox org creation status. If the org is ready, authenticates to the org.
Parameter string
the sandbox name
Parameter options
Wait: The amount of time to wait before timing out, Interval: The time interval between polling
Returns
{SandboxProcessObject} the sandbox process object

method scratchOrgCreate

scratchOrgCreate: (
    options: ScratchOrgRequest
) => Promise<ScratchOrgCreateResult>;

Creates a scratchOrg 'this' needs to be a valid dev-hub
Parameter ScratchOrgCreateOptions
Returns
{ScratchOrgCreateResult}

method setSandboxConfig

setSandboxConfig: (orgId: string, config: SandboxFields) => Promise<Org>;

set the sandbox config related to this given org
Parameter orgId
orgId of the sandbox
Parameter config
config of the sandbox

method setTracksSource

setTracksSource: (value: boolean) => Promise<void>;

Set the tracking property on the org's auth file
Parameter value
true or false (whether the org should use source tracking or not)

method supportsSourceTracking

supportsSourceTracking: () => Promise<boolean>;

method tracksSource

tracksSource: () => Promise<boolean>;

Returns true if the org uses source tracking. Side effect: updates files where the property doesn't currently exist

method updateLocalInformation

updateLocalInformation: () => Promise<void>;

Some organization information is locally cached, such as if the org name or if it is a scratch org. This method populates/updates the filesystem from information retrieved from the org.

class OrgUsersConfig

class OrgUsersConfig extends ConfigFile<OrgUsersConfig.Options> {}

A config file that stores usernames for an org.

constructor

constructor(options?: OrgUsersConfig.Options);

Constructor. **Do not directly construct instances of this class -- use OrgUsersConfig.create instead.**
Parameter options
The options for the class instance

method getOptions

static getOptions: (orgId: string) => OrgUsersConfig.Options;

Gets the config options for a given org ID.
Parameter orgId
The orgId. Generally this org would have multiple users configured.

class PermissionSetAssignment

class PermissionSetAssignment {}

A class for assigning a Salesforce User to one or more permission sets.

method create

create: (
    id: string,
    permSetString: string
) => Promise<PermissionSetAssignmentFields>;

Assigns a user to one or more permission sets.
Parameter id
A user id
Parameter permSetString
An array of permission set names.

method init

static init: (org: Org) => Promise<PermissionSetAssignment>;

Creates a new instance of PermissionSetAssignment.
Parameter org
The target org for the assignment.

class PollingClient

class PollingClient extends AsyncOptionalCreatable<PollingClient.Options> {}

This is a polling client that can be used to poll the status of long running tasks. It can be used as a replacement for Streaming when streaming topics are not available or when streaming handshakes are failing. Why wouldn't you want to use this? It can impact Salesforce API usage.

const options: PollingClient.Options = {
     async poll(): Promise<StatusResult>  {
      return Promise.resolve({ completed: true, payload: 'Hello World' });
    },
    frequency: Duration.milliseconds(10),
     timeout: Duration.minutes(1)
  };
const client = await PollingClient.create(options);
const pollResult = await client.subscribe();
console.log(`pollResult: ${pollResult}`);

constructor

constructor(options?: PollingClient.Options);

Constructor
Parameter options
Polling client options

property logger

protected logger: Logger;

method init

init: () => Promise<void>;

Asynchronous initializer.

subscribe: <T = AnyJson>() => Promise<T>;

Returns a promise to call the specified polling function using the interval and timeout specified in the polling options.

class SandboxRequestCache

class SandboxRequestCache extends TTLConfig<
    TTLConfig.Options,
    SandboxRequestCacheEntry
> {}

method getDefaultOptions

static getDefaultOptions: () => TTLConfig.Options;

method getFileName

static getFileName: () => string;

method set

static set: (
    key: string,
    sandboxProcessObject: SandboxRequestCacheEntry
) => Promise<void>;

method unset

static unset: (key: string) => Promise<void>;

class SchemaPrinter

class SchemaPrinter {}

Prints a JSON schema in a human-friendly format.

Deprecated

import chalk from 'chalk';
class MyPropertyRenderer extends SchemaPropertyRenderer {
  renderName(name) { return chalk.bold.blue(name); }
}

const printer = new SchemaPrinter(logger, schema, new MyPropertyRenderer());
printer.getLines().forEach(console.log);

constructor

constructor(
    logger: Logger,
    schema: JsonMap,
    propertyRenderer?: SchemaPropertyRenderer
);

Constructs a new SchemaPrinter.
Parameter logger
The logger to use when emitting the printed schema.
Parameter schema
The schema to print.
Parameter propertyRenderer
The property renderer.

method getLine

getLine: (index: number) => string;

Gets a ready-to-display line by index.
Parameter index
The line index to get.

method getLines

getLines: () => readonly string[];

Gets a read-only array of ready-to-display lines.

method print

print: () => void;

Prints the accumulated set of schema lines as info log lines to the logger.

class SchemaValidator

class SchemaValidator {}

Loads a JSON schema and performs validations against JSON objects.

constructor

constructor(logger: Logger, schemaPath: string);

Creates a new SchemaValidator instance given a logger and path to a schema file.
Parameter logger
An Logger instance on which to base this class's logger.
Parameter schemaPath
The path to the schema file to load and use for validation.

method load

load: () => Promise<JsonMap>;

Loads a JSON schema from the schemaPath parameter provided at instantiation.

method loadSync

loadSync: () => JsonMap;

Loads a JSON schema from the schemaPath parameter provided at instantiation.

method validate

validate: (json: AnyJson) => Promise<AnyJson>;

Performs validation of JSON data against the schema located at the schemaPath value provided at instantiation.
**Throws** *SfError{ name: 'ValidationSchemaFieldError' }* If there are known validations errors. **Throws** *SfError{ name: 'ValidationSchemaUnknownError' }* If there are unknown validations errors.
Parameter json
A JSON value to validate against this instance's target schema.
Returns
The validated JSON data.

method validateSync

validateSync: <T extends AnyJson>(json: T) => T;

Performs validation of JSON data against the schema located at the schemaPath value provided at instantiation.
**Throws** *SfError{ name: 'ValidationSchemaFieldError' }* If there are known validations errors. **Throws** *SfError{ name: 'ValidationSchemaUnknownError' }* If there are unknown validations errors.
Parameter json
A JSON value to validate against this instance's target schema.
Returns
The validated JSON data.

class ScratchOrgCache

class ScratchOrgCache extends TTLConfig<TTLConfig.Options, CachedOptions> {}

method getDefaultOptions

static getDefaultOptions: () => TTLConfig.Options;

method getFileName

static getFileName: () => string;

method unset

static unset: (key: string) => Promise<void>;

class SfdcUrl

class SfdcUrl extends URL {}

constructor

constructor(input: any, base?: any);

property PRODUCTION

static readonly PRODUCTION: string;

property SANDBOX

static readonly SANDBOX: string;

Salesforce URLs

method checkLightningDomain

checkLightningDomain: () => Promise<true | never>;

Tests whether this url has the lightning domain extension This method that performs the dns lookup of the host. If the lookup fails the internal polling (1 second), client will try again until timeout If SFDX_DOMAIN_RETRY environment variable is set (number) it overrides the default timeout duration (240 seconds)
Returns
{Promise<true | never>} The resolved ip address or never
Throws
SfError If can't resolve DNS.

method getJwtAudienceUrl

getJwtAudienceUrl: (createdOrgInstance?: string) => Promise<string>;

Returns the appropriate jwt audience url for this url Use SFDX_AUDIENCE_URL env var to override the audience url
Parameter createdOrgInstance
The Salesforce instance the org was created on. e.g. cs42 {Promise} The audience url

method isInternalUrl

isInternalUrl: () => boolean;

Tests whether this url is an internal Salesforce domain
Returns
{boolean} true if this is an internal domain

method isLightningDomain

isLightningDomain: () => boolean;

Test whether this url represents a lightning domain
Returns
{boolean} true if this domain is a lightning domain

method isLocalUrl

isLocalUrl: () => boolean;

Tests whether this url runs on a local machine
Returns
{boolean} true if this is a local machine

method isSalesforceDomain

isSalesforceDomain: () => boolean;

Tests whether this url contains a Salesforce owned domain
{boolean} true if this is a salesforce domain

method isSandboxUrl

isSandboxUrl: (createdOrgInstance?: string) => boolean;

Tests whether this url is a sandbox url
Parameter createdOrgInstance
The Salesforce instance the org was created on. e.g. cs42
Returns
{boolean}
Deprecated
- identification of a sandbox instance by URL alone is not deterministic

method isValidUrl

static isValidUrl: (input: string | URL) => boolean;

method lookup

lookup: () => Promise<string>;

Method that performs the dns lookup of the host. If the lookup fails the internal polling (1 second), client will try again until timeout If SFDX_DOMAIN_RETRY environment variable is set (number) it overrides the default timeout duration (240 seconds)
Returns
the resolved ip address.
Throws
SfError If can't resolve DNS.

method toLightningDomain

toLightningDomain: () => string;

class SfdxConfigAggregator

class SfdxConfigAggregator extends ConfigAggregator {}

A ConfigAggregator that will work with deprecated config vars (e.g. defaultusername, apiVersion). We do NOT recommend using this class unless you absolutely have to.
Deprecated

property encrypted

protected static encrypted: boolean;

property instance

protected static instance: AsyncOptionalCreatable;

method create

static create: <P, T extends AsyncOptionalCreatable<P>>(
    this: new (options?: ConfigAggregator.Options) => T,
    options?: ConfigAggregator.Options
) => Promise<T>;

method getConfigInfo

getConfigInfo: () => ConfigInfo[];

method getInfo

getInfo: (key: string) => ConfigInfo;

method getLocation

getLocation: (key: string) => Optional<ConfigAggregator.Location>;

method getPath

getPath: (key: string) => Optional<string>;

method getPropertyMeta

getPropertyMeta: (key: string) => ConfigPropertyMeta;

method getPropertyValue

getPropertyValue: <T extends AnyJson>(key: string) => Optional<T>;

class SfdxError

class SfdxError extends SfError {}

Deprecated
use SfError instead

class SfdxProject

class SfdxProject extends SfProject {}

Deprecated
use SfProject instead

class SfdxProjectJson

class SfdxProjectJson extends SfProjectJson {}

Deprecated
use SfProjectJson instead

class SfError

class SfError extends NamedError {}

A generalized sfdx error which also contains an action. The action is used in the CLI to help guide users past the error.

To throw an error in a synchronous function you must either pass the error message and actions directly to the constructor, e.g.

// To load a message bundle (Note that __dirname should contain a messages folder)
Messages.importMessagesDirectory(__dirname);
const messages = Messages.load('myPackageName', 'myBundleName');

// To throw a non-bundle based error:
throw new SfError(message.getMessage('myError'), 'MyErrorName');

constructor

constructor(
    message: string,
    name?: string,
    actions?: string[],
    exitCodeOrCause?: number | Error,
    cause?: Error
);

Create an SfError.
Parameter message
The error message.
Parameter name
The error name. Defaults to 'SfError'.
Parameter actions
The action message(s).
Parameter exitCodeOrCause
The exit code which will be used by SfdxCommand or he underlying error that caused this error to be raised.
Parameter cause
The underlying error that caused this error to be raised.

property actions

actions?: string[];

Action messages. Hints to the users regarding what can be done to fix related issues.

property code

code: any;

property context

context?: string;

The related context for this error.

property data

data?: {};

property exitCode

exitCode: number;

SfdxCommand can return this process exit code.

method setContext

setContext: (context: string) => SfError;

Sets the context of the error. For convenience this object is returned.
Parameter context
The command name.

method setData

setData: (data: unknown) => SfError;

An additional payload for the error. For convenience this object is returned.
Parameter data
The payload data.

method toObject

toObject: () => JsonMap;

Convert an SfError state to an object. Returns a plain object representing the state of this error.

method wrap

static wrap: (err: Error | string) => SfError;

Convert an Error to an SfError.
Parameter err
The error to convert.

class SfProject

class SfProject {}

Represents an SFDX project directory. This directory contains a SfProjectJson config file as well as a hidden .sfdx folder that contains all the other local project config files.
const project = await SfProject.resolve(); const projectJson = await project.resolveProjectConfig(); console.log(projectJson.sfdcLoginUrl);

constructor

protected constructor(path: string);

Do not directly construct instances of this class -- use SfProject.resolve instead.

method findPackage

findPackage: (
    predicate: (packageDir: NamedPackageDir) => boolean
) => Optional<NamedPackageDir>;

Returns the package directory.
Parameter packageName
Name of the package directory. E.g., 'force-app'

method getActivePackage

getActivePackage: () => Nullable<NamedPackageDir>;

Get the currently activated package on the project. This has no implication on sfdx-project.json but is useful for keeping track of package and source specific options in a process.

method getAliasesFromPackageId

getAliasesFromPackageId: (id: string) => string[];

method getDefaultPackage

getDefaultPackage: () => NamedPackageDir;

Get the project's default package directory defined in sfdx-project.json using first 'default: true' found. The first entry is returned if no default is specified.

method getInstance

static getInstance: (path?: string) => SfProject;

Get a Project from a given path or from the working directory.
Parameter path
The path of the project.
**Throws** *SfError{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.

method getPackage

getPackage: (packageName: string) => Optional<NamedPackageDir>;

Returns the package directory.
Parameter packageName
Name of the package directory. E.g., 'force-app'

method getPackageAliases

getPackageAliases: () => Nullable<Dictionary<string>>;

Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.

method getPackageDirectories

getPackageDirectories: () => NamedPackageDir[];

Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.

method getPackageFromPath

getPackageFromPath: (path: string) => Optional<NamedPackageDir>;

Returns the package from a file path.
Parameter path
A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls

method getPackageIdFromAlias

getPackageIdFromAlias: (alias: string) => Optional<string>;

method getPackageNameFromPath

getPackageNameFromPath: (path: string) => Optional<string>;

Returns the package name, E.g. 'force-app', from a file path.
Parameter path
A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls

method getPackagePath

getPackagePath: (packageName: string) => Optional<string>;

Returns the absolute path of the package directory ending with the path separator. E.g., /Users/jsmith/projects/ebikes-lwc/force-app/
Parameter packageName
Name of the package directory. E.g., 'force-app'

method getPath

getPath: () => string;

Returns the project path.

method getSfProjectJson

getSfProjectJson: (isGlobal?: boolean) => SfProjectJson;

Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults that are not checked in to the project specific file.
*Note:* When reading values from SfProjectJson, it is recommended to use SfProject.resolveProjectConfig instead.
This is the sync method of SfProject.resolveSfProjectJson
Parameter isGlobal
True to get the global project file, otherwise the local project config.

method getUniquePackageDirectories

getUniquePackageDirectories: () => NamedPackageDir[];

Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.
There can be multiple packages in packageDirectories that point to the same directory. This method only returns one packageDirectory entry per unique directory path. This is useful when doing source operations based on directories but probably not as useful for packaging operations that want to do something for each package entry.

method getUniquePackageNames

getUniquePackageNames: () => string[];

Get a list of the unique package names from within sfdx-project.json. Use SfProject.getUniquePackageDirectories for data other than the names.

method hasMultiplePackages

hasMultiplePackages: () => boolean;

Has multiple package directories (MPD) defined in the project.

method hasPackageAliases

hasPackageAliases: () => Promise<boolean>;

method hasPackages

hasPackages: () => boolean;

Has package directories defined in the project.

method resolve

static resolve: (path?: string) => Promise<SfProject>;

Get a Project from a given path or from the working directory.
Parameter path
The path of the project.
**Throws** *SfError{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.

method resolveProjectConfig

resolveProjectConfig: () => Promise<JsonMap>;

The project config is resolved from local and global SfProjectJson, ConfigAggregator, and a set of defaults. It is recommended to use this when reading values from SfProjectJson.
The global SfProjectJson is used to allow the user to provide default values they may not want checked into their project's source.
Returns
A resolved config object that contains a bunch of different properties, including some 3rd party custom properties.

method resolveProjectPath

static resolveProjectPath: (dir?: string) => Promise<string>;

Performs an upward directory search for an sfdx project file. Returns the absolute path to the project.
Parameter dir
The directory path to start traversing from.
**Throws** *SfError{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
**See** traverseForFile
**See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)

method resolveProjectPathSync

static resolveProjectPathSync: (dir?: string) => string;

Performs a synchronous upward directory search for an sfdx project file. Returns the absolute path to the project.
Parameter dir
The directory path to start traversing from.
**Throws** *SfError{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
**See** traverseForFileSync
**See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)

method retrieveSfProjectJson

retrieveSfProjectJson: (isGlobal?: boolean) => Promise<SfProjectJson>;

Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults that are not checked in to the project specific file.
*Note:* When reading values from SfProjectJson, it is recommended to use SfProject.resolveProjectConfig instead.
Parameter isGlobal
True to get the global project file, otherwise the local project config.

method setActivePackage

setActivePackage: (packageName: Nullable<string>) => void;

Set the currently activated package on the project. This has no implication on sfdx-project.json but is useful for keeping track of package and source specific options in a process.
Parameter packageName
The package name to activate. E.g. 'force-app'

class SfProjectJson

class SfProjectJson extends ConfigFile {}

The sfdx-project.json config object. This file determines if a folder is a valid sfdx project.
*Note:* Any non-standard (not owned by Salesforce) properties stored in sfdx-project.json should be in a top level property that represents your project or plugin.
const project = await SfProject.resolve(); const projectJson = await project.resolveProjectConfig(); const myPluginProperties = projectJson.get('myplugin') || {}; myPluginProperties.myprop = 'someValue'; projectJson.set('myplugin', myPluginProperties); await projectJson.write();
**See** [force:project:create](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm)

property BLOCKLIST

static BLOCKLIST: string[];

method addPackageAlias

addPackageAlias: (alias: string, id: string) => void;

Add a package alias to the project. If the alias already exists, it will be overwritten.
Parameter alias
Parameter id

method addPackageDirectory

addPackageDirectory: (packageDir: NamedPackageDir) => void;

Add a package directory to the project. If the package directory already exists, the new directory properties will be merged with the existing properties.
Parameter packageDir

method getContents

getContents: () => ProjectJson;

method getDefaultOptions

static getDefaultOptions: (isGlobal?: boolean) => ConfigFile.Options;

method getFileName

static getFileName: () => string;

method getPackageAliases

getPackageAliases: () => Nullable<Dictionary<string>>;

Get package aliases defined in the project.

method getPackageDirectories

getPackageDirectories: () => Promise<PackageDir[]>;

Returns the packageDirectories within sfdx-project.json, first reading and validating the file if necessary.

method getPackageDirectoriesSync

getPackageDirectoriesSync: () => NamedPackageDir[];

Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.

method getUniquePackageDirectories

getUniquePackageDirectories: () => NamedPackageDir[];

Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.
There can be multiple packages in packageDirectories that point to the same directory. This method only returns one packageDirectory entry per unique directory path. This is useful when doing source operations based on directories but probably not as useful for packaging operations that want to do something for each package entry.

method getUniquePackageNames

getUniquePackageNames: () => string[];

Get a list of the unique package names from within sfdx-project.json. Use SfProject.getUniquePackageDirectories for data other than the names.

method hasMultiplePackages

hasMultiplePackages: () => boolean;

Has multiple package directories (MPD) defined in the project.

method hasPackageAliases

hasPackageAliases: () => Promise<boolean>;

Has at least one package alias defined in the project.

method hasPackages

hasPackages: () => boolean;

Has package directories defined in the project.

method read

read: () => Promise<ConfigContents>;

method readSync

readSync: () => Dictionary<T>;

method schemaValidate

schemaValidate: () => Promise<void>;

Validates sfdx-project.json against the schema.
Set the SFDX_PROJECT_JSON_VALIDATION environment variable to true to throw an error when schema validation fails. A warning is logged by default when the file is invalid.
***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)

method schemaValidateSync

schemaValidateSync: () => void;

Validates sfdx-project.json against the schema.
Set the SFDX_PROJECT_JSON_VALIDATION environment variable to true to throw an error when schema validation fails. A warning is logged by default when the file is invalid.
***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)

method write

write: (newContents?: Dictionary<T>) => Promise<ConfigContents>;

method writeSync

writeSync: (newContents?: Dictionary<T>) => Dictionary<T>;

class StateAggregator

class StateAggregator extends AsyncOptionalCreatable {}

property aliases

aliases: AliasAccessor;

property orgs

orgs: OrgAccessor;

property sandboxes

sandboxes: SandboxAccessor;

property tokens

tokens: TokenAccessor;

method clearInstance

static clearInstance: (path?: string) => void;

Clear the cache to force reading from disk.
*NOTE: Only call this method if you must and you know what you are doing.*

method getInstance

static getInstance: () => Promise<StateAggregator>;

Reuse a StateAggregator if one was already created for the current global state directory Otherwise, create one and adds it to map for future reuse. HomeDir might be stubbed in tests

method init

protected init: () => Promise<void

@salesforce/core

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Namespaces

Variables

variable envVars

variable ORG_CONFIG_ALLOWED_PROPERTIES

variable REQUIRED_FIELDS

variable scratchOrgLifecycleEventName

variable scratchOrgLifecycleStages

variable SF_ALLOWED_PROPERTIES

variable sfdc

Deprecated

variable SFDX_ALLOWED_PROPERTIES

variable SFDX_HTTP_HEADERS

variable SUPPORTED_ENV_VARS

Functions

function findUpperCaseKeys

Parameter data

Parameter sectionBlocklist

function getJwtAudienceUrl

function getLoginAudienceCombos

function isInternalUrl

Parameter url

function matchesAccessToken

Parameter value

function scratchOrgCreate

function scratchOrgResume

function trimTo15

Parameter id

function validateApiVersion

Parameter value

function validateEmail

Parameter value

function validatePathDoesNotContainInvalidChars

Parameter value

function validateSalesforceId

Parameter value

Classes

class AuthInfo

constructor

Parameter options

method getAuthorizationUrl

Parameter options

method getClientId

method getConnectionOptions

method getDefaultInstanceUrl

Returns

method getDevHubAuthInfos

method getFields

Parameter decrypt

method getOrgFrontDoorUrl

method getRedirectUri

method getSfdxAuthUrl

method getUsername

method handleAliasAndDefaultSettings

Parameter sideEffects

method hasAuthentications

method identifyPossibleScratchOrgs

Parameter fields

Parameter orgAuthInfo

method init

method isAccessTokenFlow

method isJwt

method isOauth

method isRefreshTokenFlow

method isUsingAccessToken

method listAllAuthorizations

Parameter orgAuthFilter

Parameter orgAuthFilter

Returns

method parseSfdxAuthUrl

Parameter sfdxAuthUrl