auth:salesforce:save

Encrypt and save credentials that can be used to connect to a Salesforce organization. Credentials can be saved either locally or remotely, and can also optionally be scoped to specific environments.

Alternatively, this command can be used to clear out previously saved credentials.

warning

Your encryption keys are secrets and should be treated as such. They can be used to un-encrypt credentials that in turn can be used to access your Salesforce organizations or your remote Git repository. The OrgFlow CLI is designed in a way that all encryption keys are generated (and optionally saved) locally- in other words, we as a company never get to see them. If you lose or forget your encryption key, it is not possible for us to recover any encrypted credentials that you may have saved either locally or remotely in our state store.

Precedence and scope

When setting credentials, it is important to understand how they are retrieved and applied in subsequent processes.

There are two locations where credentials can be saved: locally, and remotely in the stack state store. Additionally- there are also two scopes for credentials: environment specific, and stack level (or base). This means that there are four locations that could potentially contain credentials for each environment. When retrieving credentials, OrgFlow needs to be able to deterministically be able to choose which location takes precedence.

It does this by checking for credentials in one location, and if it finds credentials there then it uses those credentials. Otherwise it will check the next location, and so on until either the credentials are discovered, or all possible locations are exhausted (whichever happens first). The precedence is (starting at the top):

1. Environment specific credentials saved locally
2. Environment specific credentials saved on the remote stack state store
3. Stack level (base) credentials saved locally
4. Stack level (base) credentials saved on the remote stack state store

Where credentials are saved is controlled by the --location and --environment options.

Options

• --stack=<stackName>

  The name of the stack to target. Stack names are case-insensitive. Stacks are specific to license keys, and you can see a list of all available stacks with the stack:list command.

  This value is required if no valid default stack has been set, or if you would like to target a stack other than the one that is currently the default stack. You can use the stack:setdefault command to set or change the default stack.

• -k|--encryptionKey=<key>

  The key used to encrypt or decrypt stored credentials.

  Required if:

  • You want the process to utilise previously encrypted credentials, or if you want the process to save credentials
  • AND the encryption key has not been saved locally with the auth:key:save command, or the key that has been saved locally is not the key that you wish to use

• --environment=<environmentName>

  If specified, the credentials to be saved will be specific to the environment specified. Omit to save the credentials at the stack-level. When retrieving saved credentials, the OrgFlow CLI will first to check to see there is are saved credentials that are specific to the environment that it is trying to connect to. If there are no credentials available at the environment level then the CLI will then fall back to using credentials set the stack level.

  

  note

  If credentials are set at the stack level, they should be in a valid format for the production Salesforce organization. This is because the OrgFlow CLI will try to transform stack level credentials into environment specific credentials should it need to.

  For example- imagine an environment called EnvironmentA which is backed by a sandbox called SandboxA, and a production Salesforce username user@orgflow.io:

  • If you save credentials at the environment level, then the username needs to be user@orgflow.io.sandboxa (because no username transformation is applied to environment specific credentials).
  • If you save credentials at the stack level, then the username needs to be user@orgflow.io. OrgFlow will automatically append .sandboxa to this username when connecting to SandboxA because it expects production credentials to be stored at the stack level, which in turn allows them to be transformed to sandbox credentials.
  • If you save credentials at the stack level, but use a sandbox specific username (e.g. user@orgflow.io.sandboxa), then OrgFlow will transform this username to user@orgflow.io.sandboxa.sandboxa when connecting to SandboxA. This is probably not what you want, and authentication will probably fail.

  See Credential Inference for more details.

  Environment names are case-insensitive.

• -u|--username=<username>

  Required. Prompted for when not specified, and possible to do so.

  The username to save.

• -p|--password=<password>

  Required. Prompted for when not specified, and possible to do so.

  The password to save.

  

  note

  Your Salesforce org may be configured in a way that requires a Security Token to be supplied with your password. In this case, you must append your security token to the end of the password that you save. For example, if your password is OrgFlow123, and your token is abcdefg, then you should use OrgFlow123abcdefg.

  

  tip

  Both --username and --password must be supplied in pairs. It is not possible to specify a value for only one but not the other.

  An empty value for both (i.e. --username= --password=) indicates a wish to clear any saved credentials.

• --location=[Local|StateStore]

  Default: Local.

  The physical location to save the credentials.

  • Local: The credentials are saved locally on disk and are specific to the current machine that the auth:salesforce:save command is executed on. This is best suited to manual execution where you have multiple team members interacting with the same stack. It allows accountability by allowing each user to authenticate with their own Salesforce account.
  • StateStore: The credentials are saved remotely in our stack State Store. They cannot be read by a third party (including OrgFlow's employees or representatives) without the third party knowing the encryption key that you used to encrypt them. These credentials can be accessed by anyone with access to the stack and the encryption key. This is best suited to scenarios where you might need all deployments to be performed by the same user, or where you have an 'API only' account that is used by automated processes (such as CI/CD).

The following options are global across all commands:

• -h|--help

  If specified, prints help for this command instead of executing it.

• -l|--licenseKey=<key>

  The License Key you were issued to allow you to use the OrgFlow CLI. If a valid key is supplied, it is stored locally on the machine so that it does not need to be specified again on the next execution.

• --acceptEula

  If specified, you are signifying that you accept our End User License Agreement (EULA). You only need to specify this once per device, because your acceptance will be cached on the device (you can pass --acceptEula=false if you wish to clear this). You must accept our EULA to be able to run most OrgFlow commands.

• --logTo=<filePath>

  If specified, a log file is written to the specified path. The specified path may contain one or more tokens; see Logging for more information.

• --logLevel=[Verbose|Debug|Information|Warning|Error|Fatal]

  Default: Information

  The minimum log level to be written to the log file; logs below this level will not be written. Only effective if a valid value for --logTo has been specified.

• --diagnostic=[Auto|Always|Never]

  Default: Auto

  If the CLI encounters an exception then it will ask (where possible) the user whether or not to create a Diagnostic Bundle and write it to disk. If it is not able to prompt then no action is taken. This is the default behaviour (Auto).

  You can change this default behaviour (and suppress the prompt) by specifying either Always or Never (which will always write the bundle or never write the bundle, respectively). This is particularly useful in a CI/CD context, where the CLI may not be able to prompt, but you still want to create diagnostic bundles for all failures.

• --diagnosticDirPath=<directoryPath>

  If specified, sets the location to write the Diagnostic Bundle (if any). If not specified, a default location will automatically be chosen. This default location depends on a number of factors, including the operating system and some file-system based restrictions that might be in place. The location that the diagnostic bundle is ultimately written to is always included in the standard error output of the CLI.

• --noConfirm

  If specified, suppresses confirmation prompts that the CLI might raise before performing destructive or dangerous procedures. If suppressed, the CLI assumes that the prompts would have been answered positively and continues with execution.

• --progress=[Interactive|Never|Always]

  Default: Interactive

  Controls how progress is printed to the standard error stream:

  • Interactive: Progress is sent to the standard error stream only if the standard error stream is connected to an interactive terminal.
  • Never: Progress is not sent to the standard error stream.
  • Always: Progress is sent to the standard error stream, even if that stream has been redirected.

• --tempDir=<directoryPath>

  If specified, sets the location to use as storage for files that may need to be stored on disk temporarily during command execution. For example, the location on disk where zip files containing metadata from Salesforce are downloaded to before they are unzipped.

  If not specified, the CLI will automatically choose an appropriate location on disk (usually in the current user's temporary storage location). This automatically chosen location may be deeply nested within a drive, which may be problematic if the operating system imposes limits on file path lengths and the files placed into temporary storage have particularly long paths or names.

• --json

  Switches the format of the output sent to the standard output stream to JSON. This is the most verbose output available, and is useful for scripting or automation.

• --forceSignIn.

  If specified, the CLI will ignore any cached Salesforce access tokens, and will require the Salesforce authentication process to be re-completed for each organisation that the command connects to.

• --maxTransientErrorRetries=<count>.

  If no value is specified, the CLI will indefinitely retry any process that fails due to a transient error. This is the default behaviour, and allows for resilience against temporary issues that might otherwise cause a process to fail.

  Specify a positive integer value to prevent indefinite retries. Each process that fails due to a transient error will be retried up to a maximum amount of times specified. For example, --maxTransientErrorRetries=5: Each process that fails will be re-tried up to a maximum of five times. If an earlier process fails four times but then succeeds on the fifth attempt, the counter is reset for the next process.

  Specify --maxTransientErrorRetries=0 to disable transient failure retries.

• --maxTransientErrorDelay=<seconds>.

  Default: 60

  Processes retried due to a transient error are delayed by a back-off policy that gradually increases the time to wait between retries. Specify a non-negative integer value as the maximum amount of seconds to wait between attempts.

  Specify --maxTransientErrorDelay=0 to disable the back-off policy and always instantly retry failed processes.

Examples

Encrypt and locally save stack level (base) credentials:

orgflow auth:salesforce:save --username=user@orgflow.io --password=mypassword

Encrypt and remotely save stack level (base) credentials in the stack state store:

orgflow auth:salesforce:save --username=user@orgflow.io --password=mypassword --location=StackService

Encrypt and remotely save environment specific credentials in the stack state store:

orgflow auth:salesforce:save --environment=qa --username=user@orgflow.io.qa --password=mypassword --location=StackService

Clear out previously locally saved environment specific credentials:

orgflow auth:salesforce:save --environment=dev1 --username= --password= --location=Local