I have an org connected in sfdx with an alias that I would like to change.

I don't see an alias key in the corresponding ~/.sfdx/org.json file. I also don't see anything mentioned about this on the org commands documentation.

Is there a way to do this via sfdx-cli without connecting to or creating the org again?

7 Answers 7


You can use force:alias:set:

sfdx force:alias:set newAlias=username@domain.com

The original alias is automatically removed/renamed with this command.

  • Thanks @sfdcfox, I looked at the alias commands but wasn't aware that this scenario is actually an alias to a username and not an org.
    – Brand0R
    Jan 8, 2020 at 19:04
  • 1
    As of CLI version 7.75.0 using the "sfdx force:alias:set" command doesn't change the alias that is shown when you do a "sfdx force:org:list". At least not for me.
    – rStrunk
    Oct 6, 2020 at 20:10
  • 1
    @rStrunk Thanks for the comment. I've brought this to the attention of the DX team. I'll update this answer when I get a response.
    – sfdcfox
    Oct 6, 2020 at 21:13
  • 3
    @Shane force:alias:set, here, is the old command (still apparently works). You'll want to use the new alias:set, which appears to fix the problem with the old command.
    – sfdcfox
    Oct 20, 2020 at 19:20
  • 1
    @jbyrd The org itself does not have an alias in DX. The listed alias is for the user. In most scratch org setups, this is synonymous, as you normally have one user in the org you work with, and you can call your alias anything you want, even vscodeOrg, but it's still just an alias to a user (note: this means you shouldn't log in to the same org with different users, as you'll create a lot of conflicts in your source push/pulls).
    – sfdcfox
    Jul 23, 2021 at 19:42

I'm not sure if the spec changed for sfdx force:alias:set but the command that worked for me involved specifying the username, as follows:

sfdx force:alias:set my-new-alias=foo-0rjdhesx8atr@example.com

Then the results of sfdx force:org:list is as follows:

 ALIAS        USERNAME                       ORG ID              EXPIRATION DATE
  ───────────  ─────────────────────────────  ──────────────────  ───────────────
  my-new-alias  foo-0rjdhesx8atr@example.com  00D21000000HTDoXXO  2020-10-21
  • This worked . thanks
    – Cloud Man
    Apr 13, 2022 at 11:09

It looks like the alias commands have moved from being under the force namespace to being in their own namespace.


sfdx alias:set new-alias=login@example.com
  • Good catch. sfdx force:alias does automatically map to sfdx alias
    – Shanerk
    Oct 20, 2020 at 18:49

I was able to directly edit ~/.sfdx/alias.json

  • 1
    This was the easiest, I do not know how many hours I have spent trying to remove unnecessary environments. thank you. Apr 28, 2021 at 16:57
  • 1
    This was the easiest option. Running the "alias:set" was successful, but it never updated the alias until the entry was removed from the alias.json file. Thanks May 19, 2021 at 16:56

I had to also do sfdx alias:unset blah to remove an alias I didn't want to have in my life


In bash, using the support of jq, I set up a function like below NOTE* the below function is pointing to "nonScratchOrgs" so it would need to be tweaked if we are looking to change aliases for scratch orgs as well:

dx-alias-replace-by-name() {
    echo What is the **OLD** alias name you would like to replace?
    read OLD_ALIAS
    echo What is the **NEW** alias name you would like to set?
    read NEW_ALIAS
    org_list=$(sfdx force:org:list --json)
    ORIGINAL_USERNAME=$(echo $org_list | jq --arg alias $oldalias -r '.result.nonScratchOrgs[] | select(.alias == $alias )' | jq -r '.username')
    echo sfdx alias:set $NEW_ALIAS=$ORIGINAL_USERNAME --json
    time sfdx alias:set $NEW_ALIAS=$ORIGINAL_USERNAME --json


sfdx alias:unset aliasvalue

as Eugene mentioned,This is the right way.

Setting an empty alias now marks the value as undefined and causes issue.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .