plugin-settings

Config and alias commands for the sf Salesforce CLI

NOTE: This repo combines plugin-config and plugin-alias for sf.

If you are looking for the sfdx command repos, they can be found here: plugin-config and plugin-alias

This plugin is bundled with the Salesforce CLI. For more information on the CLI, read the getting started guide.

We always recommend using the latest version of these commands bundled with the CLI, however, you can install a specific version or tag if needed.

Install

sf plugins install settings@x.y.z

Issues

Please report any issues at https://github.com/forcedotcom/cli/issues

Contributing

1. Please read our Code of Conduct
2. Create a new issue before starting your project so that we can keep track of what you are trying to add/fix. That way, we can also offer suggestions or let you know if there is already an effort in progress.
3. Fork this repository.
4. Build the plugin locally
5. Create a topic branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
6. Edit the code in your fork.
7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
8. Sign CLA (see CLA below).
9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.

CLA

External contributors will be required to sign a Contributor's License Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.

Build

To build the plugin locally, make sure to have yarn installed and run the following commands:

# Clone the repository
git clone git@github.com:salesforcecli/plugin-settings

# Install the dependencies and compile
yarn install
yarn build

To use your plugin, run using the local ./bin/dev.js or ./bin/dev.cmd file.

# Run using local run file.
./bin/dev config

There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.

# Link your plugin to the sf cli
sf plugins link .
# To verify
sf plugins

Commands

• sf alias list
• sf alias set
• sf alias unset
• sf config get
• sf config list
• sf config set
• sf config unset

sf alias list

List all aliases currently set on your local computer.

USAGE
  $ sf alias list [--json] [--flags-dir <value>]

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List all aliases currently set on your local computer.

  Aliases are global, which means that you can use all the listed aliases in any Salesforce DX project on your computer.

ALIASES
  $ sf force alias list

EXAMPLES
  List all the aliases you've set:

    $ sf alias list

See code: src/commands/alias/list.ts

sf alias set

Set one or more aliases on your local computer.

USAGE
  $ sf alias set [--json] [--flags-dir <value>]

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Set one or more aliases on your local computer.

  Aliases are user-defined short names that make it easier to use the CLI. For example, users often set an alias for a
  scratch org usernames because they're long and unintuitive. Check the --help of a CLI command to determine where you
  can use an alias.

  You can associate an alias with only one value at a time. If you set an alias multiple times, the alias points to the
  most recent value. Aliases are global; after you set an alias, you can use it in any Salesforce DX project on your
  computer.

  Use quotes to specify an alias value that contains spaces. You typically use an equal sign to set your alias, although
  you don't need it if you're setting a single alias in a command.

ALIASES
  $ sf force alias set

EXAMPLES
  Set an alias for a scratch org username:

    $ sf alias set my-scratch-org=test-sadbiytjsupn@example.com

  Set multiple aliases with a single command:

    $ sf alias set my-scratch-org=test-sadbiytjsupn@example.com my-other-scratch-org=test-ss0xut7txzxf@example.com

  Set an alias that contains spaces:

    $ sf alias set my-alias='alias with spaces'

  Set a single alias without using an equal sign:

    $ sf alias set my-scratch-org test-ss0xut7txzxf@example.com

See code: src/commands/alias/set.ts

sf alias unset

Unset one or more aliases that are currently set on your local computer.

USAGE
  $ sf alias unset [--json] [--flags-dir <value>] [-a] [-p]

FLAGS
  -a, --all        Unset all currently set aliases.
  -p, --no-prompt  Don't prompt the user for confirmation when unsetting all aliases.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Unset one or more aliases that are currently set on your local computer.

  Aliases are global, so when you unset one it's no longer available in any Salesforce DX project.

ALIASES
  $ sf force alias unset

EXAMPLES
  Unset an alias:

    $ sf alias unset my-alias

  Unset multiple aliases with a single command:

    $ sf alias unset my-alias my-other-alias

  Unset all aliases:

    $ sf alias unset --all [--no-prompt]

See code: src/commands/alias/unset.ts

sf config get

Get the value of a configuration variable.

USAGE
  $ sf config get [--json] [--flags-dir <value>] [--verbose]

FLAGS
  --verbose  Display whether the configuration variables are set locally or globally.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Get the value of a configuration variable.

  Run "sf config list" to see the configuration variables you've already set and their level (local or global).

  Run "sf config set" to set a configuration variable. For the full list of available configuration variables, see
  https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm.

ALIASES
  $ sf force config get

EXAMPLES
  Get the value of the "target-org" configuration variable.

    $ sf config get target-org

  Get multiple configuration variables and display whether they're set locally or globally:

    $ sf config get target-org api-version --verbose

See code: src/commands/config/get.ts

sf config list

List the configuration variables that you've previously set.

USAGE
  $ sf config list [--json] [--flags-dir <value>]

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List the configuration variables that you've previously set.

  A config variable can be global or local, depending on whether you used the --global flag when you set it. Local
  config variables apply only to the current project and override global config variables, which apply to all projects.
  You can set all config variables as environment variables. Environment variables override their equivalent local and
  global config variables.

  The output of this command takes into account your current context. For example, let's say you run this command from a
  Salesforce DX project in which you've locally set the "target-org" config variable. The command displays the local
  value, even if you've also set "target-org" globally. If you haven't set the config variable locally, then the global
  value is displayed, if set. If you set the SF_TARGET_ORG environment variable, it's displayed as such and overrides
  any locally or globally set "target-org" config variable.

  For the full list of available configuration variables, see
  https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm.

ALIASES
  $ sf force config list

EXAMPLES
  List the global and local configuration variables that apply to your current context:

    $ sf config list

See code: src/commands/config/list.ts

sf config set

Set one or more configuration variables, such as your default org.

USAGE
  $ sf config set [--json] [--flags-dir <value>] [-g]

FLAGS
  -g, --global  Set the configuration variables globally, so they can be used from any Salesforce DX project.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Set one or more configuration variables, such as your default org.

  Use configuration variables to set CLI defaults, such as your default org or the API version you want the CLI to use.
  For example, if you set the "target-org" configuration variable, you don't need to specify it as a "sf deploy
  metadata" flag if you're deploying to your default org.

  Local configuration variables apply only to your current project. Global variables, specified with the --global flag,
  apply in any Salesforce DX project.

  The resolution order if you've set a flag value in multiple ways is as follows:

  1. Flag value specified at the command line.
  2. Local (project-level) configuration variable.
  3. Global configuration variable.

  Run "sf config list" to see the configuration variables you've already set and their level (local or global).

  If you're setting a single config variable, you don't need to use an equal sign between the variable and value. But
  you must use the equal sign if setting multiple config variables.

  For the full list of available configuration variables, see
  https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm.

ALIASES
  $ sf force config set

EXAMPLES
  Set the local target-org configuration variable to an org username:

    $ sf config set target-org me@my.org

  Set the local target-org configuration variable to an alias:

    $ sf config set target-org my-scratch-org

  Set the global target-org and target-dev-hub configuration variables using aliases:

    $ sf config set --global target-org=my-scratch-org target-dev-hub=my-dev-hub

See code: src/commands/config/set.ts

sf config unset

Unset local or global configuration variables.

USAGE
  $ sf config unset [--json] [--flags-dir <value>] [-g]

FLAGS
  -g, --global  Unset the configuration variables globally.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Unset local or global configuration variables.

  Local configuration variables apply only to your current project. Global configuration variables apply in any
  Salesforce DX project.

  For the full list of available configuration variables, see
  https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm.

ALIASES
  $ sf force config unset

EXAMPLES
  Unset the local "target-org" configuration variable:

    $ sf config unset target-org

  Unset multiple configuration variables globally:

    $ sf config unset target-org api-version --global

See code: src/commands/config/unset.ts