Salesforce DX Developer Guide
jNewer Version Available
Salesforce DX Usernames and Orgs
When you create a scratch org, the CLI generates a username. The username looks like an email address, such as test-wvkpnfm5z113@example.com. You don’t need a password to connect to or open a scratch org, although you can generate one later with the org generate password command.
Salesforce recommends that you set the org that you connect to the most during development as your default org. The easiest way to set it is when you log in to a Dev Hub org or create a scratch org; you can also use the config commands. Specify the --set-default-dev-hub or --set-default flag, respectively. You can also create an alias to make the org’s usernames more readable and intuitive. You can use usernames or their aliases interchangeably for all CLI commands that connect to an org.
These examples set the default org and aliases when you log in and authorize an org, in this case a Dev Hub org, and then when you create a scratch org.
To verify whether a CLI command requires an org connection, look at its flag list with the -h flag. Commands that have the --target-dev-hub flag connect to the Dev Hub org. Similarly, commands that have --target-org connect to scratch orgs, sandboxes, and so on. This example displays the flag list and help information about org create scratch.
When you run a CLI command that requires an org connection and you don’t specify a username, the command uses the default. To display all the orgs that you've authorized or created, run org list. The default Dev Hub and scratch orgs are marked with an emoji on the left; see the legend at the end of the display for details.
Let's run through a few examples. This example deploys source code to the org that you've set as the default.
To specify an org other than the default, use --target-org. For example, let’s say you created a scratch org with the alias my-other-scratch-org. It’s not the default but you still want to deploy source to it.
This example shows how to use the --target-dev-hub flag to specify a non-default Dev Hub org when creating a scratch org.
More About Setting Default Orgs
If you’ve already created a scratch org, you can set it, or any other org, as your default by running the config set command from your project directory.
The command sets the value locally, so it works only for the current project. To use the default org for all projects on your computer, specify the --global flag. You can run this command from any directory. Local project defaults override global defaults.
The process is similar to set a default Dev Hub org, except you use the target-dev-hub config variable.
To unset a config variable, run the config unset command. Use the --global flag to unset it for all your Salesforce DX projects.
To view all the configuration variables you’ve set, run config list; if you run it from a project directory it also lists the local ones.
More About Aliasing
Use the alias set command to set an alias for a scratch org you’ve already created, or any org after you’ve authorized it. You can create an alias for any org: Dev Hub, scratch org, production, sandbox, and so on. So when you issue a command that requires the org’s username, using an easily-remembered alias speeds things up.
An alias also makes it easy to set a default org. The previous example of using config set to set target-org now becomes much more digestible when you use an alias rather than the actual username.
Set multiple aliases with a single command by separating the name-value pairs with a space; in this case you must use the equal sign.
You can associate an alias with only one username at a time. If you set it multiple times, the alias points to the most recent username. For example, if you run the following two commands, the alias my-org is set to test-wvkpnfm5z113@example.com.
To view all aliases that you’ve set, use one of the following commands.
To remove an alias, use the alias unset command.
List All Your Orgs
Use the org list command to display the usernames and aliases for the orgs that you’ve authorized and the active scratch orgs that you’ve created.
The output lists the orgs that you’ve authorized or created, including Dev Hub orgs, production orgs, scratch orgs, and sandboxes. The table displays the usernames that you specified when you authorized the orgs, their aliases, their IDs, and whether the CLI can connect to it. An emoji on the left points to the default org or Dev Hub; refer to the legend at the bottom for details. Scratch orgs also display their expiration dates.
To view more information, such as the scratch org creation date and associated DevHub org, and instance URL for all orgs, use the --verbose flag.
Use the --clean flag to remove non-active scratch orgs from the list. The command prompts you before it does anything.