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 do not need a password to connect to or open a scratch org, although you can generate one later with the force:user:password:generate command.
Salesforce recommends that you set a default username for the orgs that you connect to the most during development. The easiest way to do this is when you authorize a Dev Hub org or create a scratch org. Specify the --setdefaultdevhubusername or --setdefaultusername parameter, respectively, from within a project directory. You can also create an alias to give the usernames more readable names. You can use usernames or their aliases interchangeably for all CLI commands that connect to an org.
These examples set the default usernames and aliases when you authorize an org and then when you create a scratch org.
1sfdx force:auth:web:login --setdefaultdevhubusername --setalias my-hub-org
2sfdx force:org:create --definitionfile my-org-def.json --setdefaultusername --setalias my-scratch-orgTo verify whether a CLI command requires an org connection, look at its parameter list with the --help parameter. Commands that have the --targetdevhubusername parameter connect to the Dev Hub org. Similarly, commands that have --targetusername connect to scratch orgs, sandboxes, and so on. This example displays the parameter list and help information about force:org:create.
1sfdx force:org:create --helpWhen you run a CLI command that requires an org connection and you don’t specify a username, the command uses the default.To see your default usernames, run force:org:list to display all the orgs you've authorized or created.The default Dev Hub and scratch orgs are marked on the left with (D) and (U), respectively.
Let's run through a few examples to see how this works. This example pushes source code to the scratch org that you've set as the default.
1sfdx force:source:pushTo specify an org other than the default, use --targetusername. For example, let’s say you created another scratch org with alias my-other-scratch-org. It’s not the default but you still want to push source to it.
1sfdx force:source:push --targetusername my-other-scratch-orgThis example shows how to use the --targetdevhubusername parameter to specify a non-default Dev Hub org when creating a scratch org.
1sfdx force:org:create --targetdevhubusername jdoe@mydevhub.com --definitionfile my-org-def.json --setalias yet-another-scratch-orgMore About Setting Default Usernames
If you’ve already created a scratch org, you can set the default username with the force:config:set command from your project directory.
1sfdx force:config:set defaultusername=test-wvkpnfm5z113@example.comThe command sets the value locally, so it works only for the current project. To use the default username for all projects on your computer, specify the --global parameter. You can run this command from any directory. Local project defaults override global defaults.
1sfdx force:config:set defaultusername=test-wvkpnfm5z113@example.com --globalThe process is similar to set a default Dev Hub org, except you use the defaultdevhubusername config value.
1sfdx force:config:set defaultdevhubusername=jdoe@mydevhub.comMore About Aliasing
Use the force:alias:set command to set an alias for an org or after you’ve authorized an org. You can create an alias for any org: Dev Hub, scratch, production, sandbox, and so on. So when you issue a command that requires the org username, using an alias for the org that you can easily remember can speed up things.
1sfdx force:alias:set my-scratch-org=test-wvkpnfm5z113@example.comAn alias also makes it easy to set a default username. The previous example of using force:config:set to set defaultusername now becomes much more digestible when you use an alias rather than the username.
1sfdx force:config:set defaultusername=my-scratch-orgSet multiple aliases with a single command by separating the name-value pairs with a space.
1sfdx force:alias:set org1=<username> org2=<username>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.
1sfdx force:alias:set my-org=test-blahdiblah@whoanellie.net
2sfdx force:alias:set my-org=test-wvkpnfm5z113@example.comTo view all aliases that you’ve set, use one of the following commands.
1sfdx force:alias:list
2sfdx force:org:listTo remove an alias, set it to nothing.
1sfdx force:alias:set my-org=List All Your Orgs
Use the force:org:list command to display the usernames for the orgs that you’ve authorized and the active scratch orgs that you’ve created.
1sfdx force:org:list
2=== Orgs
3 ALIAS USERNAME ORG ID CONNECTED STATUS
4 ----------- -------------------- -------- ----------------
5 DD-ORG jdoe@dd-204.com 00D...OEA Connected
6(D) devhuborg jdoe@mydevhub.com 00D...MAC Connected
7
8
9 ALIAS SCRATCH ORG NAME USERNAME ORG ID EXPIRATION DATE
10 ---------- ------------ -------------------------- --------- ----------
11 my-scratch Your Company test-wvkm5z113@example.com 00D...UAI 2017-06-13
12(U) scratch208 Your Company test-wvkm5z113@example.com 00D...UAY 2017-06-13The top section of the output lists the non-scratch orgs that you’ve authorized, including Dev Hub orgs, production orgs, and sandboxes. The output displays the usernames that you specified when you authorized the orgs, their aliases, their IDs, and whether the CLI can connect to it. A (D) on the left points to the default Dev Hub org username.
The lower section lists the active scratch orgs that you’ve created and their usernames, org IDs, and expiration dates. A (U) on the left points to the default scratch org username.
To view more information about scratch orgs, such as the create date, instance URL, and associated Dev Hub org, use the --verbose parameter.
1sfdx force:org:list --verboseUse the --clean parameter to remove non-active scratch orgs from the list. The command prompts you before it does anything.
1sfdx force:org:list --clean