Salesforce DX Usernames and Orgs

Many CLI commands connect to an org to complete their task. For example, the force:org:create command, which creates a scratch org, connects to a Dev Hub org. The force:source:push|pull commands synchronize source code between your project and a scratch org. In each case, the CLI command requires a username to determine which org to connect to. Usernames are unique within the entire Salesforce ecosystem and have a one-to-one association with a specific org.

The examples in this topic might refer to CLI commands that you are not yet familiar with. For now, focus on how to specify the usernames, configure default usernames, and use aliases. The CLI commands are described later.

Note

When you create a scratch org, the CLI generates a username. The username looks like an email address, such as test-gjt2ycpivtpz@your_company.net. 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-org

To 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 --help

When 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:push

To 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-org

This 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-org

More 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-ymmlqf29req5@your_company.net

The 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-ymmlqf29req5@your_company.net --global

The process is similar to set a default Dev Hub org, except you use the defaultdevhubusername config value.

1sfdx force:config:set defaultdevhubusername=jdoe@mydevhub.com

More 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-ymmlqf29req5@your_company.net

An 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-org

Set 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-ymmlqf29req5@your_company.net.

1sfdx force:alias:set my-org=test-blahdiblah@whoanellie.net
2sfdx force:alias:set my-org=test-ymmlqf29req5@your_company.net

To view all aliases that you’ve set, use one of the following commands.

1sfdx force:alias:list
2sfdx force:org:list

To 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) devhuborg208  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-ymmlqf5@a_company.net 00D...UAI 2017-06-13
12(U) scratch208 Your Company     test-gjt2ycz@b_company.net 00D...UAY 2017-06-13

The 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 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 --verbose

Use 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

Salesforce DX Developer Guide

Salesforce DX Usernames and Orgs

More About Setting Default Usernames

More About Aliasing

List All Your Orgs

See Also: