Skip to content

hardis:org:select

Description

Command Behavior

This command requires human interaction and must be called manually, preferably from the VS Code SFDX Hardis UI. It is not suitable for automation or AI agent usage.

Allows you to select a Salesforce org and set it as your default, optionally filtering by Dev Hub or scratch orgs.

This command simplifies switching between different Salesforce environments. It presents an interactive list of your authenticated orgs, enabling you to quickly set a new default org for subsequent Salesforce CLI commands.

Key functionalities:

  • Interactive Org Selection: Displays a list of your authenticated Salesforce orgs, allowing you to choose one.
  • Default Org Setting: Sets the selected org as the default for your Salesforce CLI environment.
  • Org Naming: An org you connect is given an alias, so it shows up under a short name instead of its username everywhere afterwards. Pass --alias, or accept the suggestion the command makes from the org's instance URL. The question comes before the browser opens when you gave the URL of the org, and after the login when you went through login.salesforce.com or test.salesforce.com. An org that already has an alias keeps it when you reconnect it, and an org of the list that has none is offered one.
  • Dev Hub Filtering: The --devhub flag filters the list to show only Dev Hub orgs.
  • Scratch Org Filtering: The --scratch flag filters the list to show only scratch orgs related to your default Dev Hub.
  • Connection Verification: Ensures that the selected org is connected and prompts for re-authentication if necessary.
  • Forced Reconnection: The --reconnect flag skips the connection check and goes straight to re-authentication.
Technical explanations

The command's technical implementation involves:

  • Interactive Org Prompt: Uses the promptOrg utility to display a list of available Salesforce orgs and allows the user to select one. It passes the devHub and scratch flags to promptOrg to filter the displayed list.
  • Default Org Configuration: The promptOrg utility (internally) handles setting the selected org as the default using Salesforce CLI's configuration mechanisms.
  • Connection Check: It calls makeSureOrgIsConnected to verify the connection status of the selected org and guides the user to re-authenticate if the org is not connected.
  • Forced Reconnection: When --reconnect is used, the command skips the connection check and directly triggers sf org login web with --set-default and --alias, combining re-authentication, default-setting and naming into a single CLI call.
  • Org Naming: The alias is passed to sf org login web --alias whenever it is known before the login: --alias, the alias the username already has, or the answer to a prompt whose default value is built from the instance URL. sf alias set is only called when the instance URL is not known before the login (login.salesforce.com, test.salesforce.com), or when no login happens.
  • Salesforce CLI Integration: It relies on Salesforce CLI's underlying commands for org listing and authentication.
  • Authentication Failure Detection: Errors raised while authenticating are re-thrown instead of being swallowed by the oclif hook mechanism, and the command fails if it ends without a connected org.

Learn by doing

The free Salesforce DevOps with sfdx-hardis course runs this command, click by click, on an org of your own:

Parameters

Name Type Description Default Required Options
agent boolean Run in non-interactive mode for agents and automation
alias
-a		 option Alias to give the org you connect. When omitted, the command suggests one built from the org instance URL
debug
-d		 boolean Activate debug mode (more logs)
devhub
-h		 boolean Also connect associated DevHub
flags-dir option Import flag values from a directory.
instance-url option Instance URL to use for login when reconnecting (e.g. https://myorg.salesforce.com). Required with --reconnect.
json boolean Format output as json.
reconnect
-r		 boolean Force re-authentication (skip connection check and go straight to login)
scratch
-s		 boolean Select scratch org related to default DevHub
set-default boolean Set the selected org as default target-org (or target-dev-hub if --devhub is used). Use --no-set-default to skip. If omitted, you will be prompted.
skipauth boolean Skip authentication check when a default username is required
username
-t		 option Username of the org you want to authenticate (overrides the interactive prompt)
websocket option Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:org:select

$ sf hardis:org:select --devhub

$ sf hardis:org:select --alias acme-dev

$ sf hardis:org:select --username myuser@example.com --set-default

$ sf hardis:org:select --username myuser@example.com --no-set-default

$ sf hardis:org:select --reconnect --instance-url https://myorg.salesforce.com --set-default

$ sf hardis:org:select --agent --set-default

Comments