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?

8 Answers 8


You can use force:alias:set:

sfdx force:alias:set [email protected]

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
    Commented 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
    Commented 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
    Commented 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
    Commented 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
    Commented 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 [email protected]

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

 ALIAS        USERNAME                       ORG ID              EXPIRATION DATE
  ───────────  ─────────────────────────────  ──────────────────  ───────────────
  my-new-alias  [email protected]  00D21000000HTDoXXO  2020-10-21
  • This worked . thanks
    – Cloud Man
    Commented 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 [email protected]
  • Good catch. sfdx force:alias does automatically map to sfdx alias
    – Shanerk
    Commented 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. Commented 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 Commented 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


Here is a quick update. If you're using a new recommended version of Salesforce CLI (sf commands instead of sfdx), use the sf alias set command:

Set an alias for a scratch org username:

sf alias set [email protected]

Set multiple aliases with a single command:

sf alias set [email protected] [email protected]

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 [email protected]


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 .