switching-org
forcedotcom/sf-skills
Switch the active Salesforce org for CLI commands using the Salesforce CLI.
What is switching-org?
Changes which Salesforce org (default target-org) the Salesforce CLI commands run against. Use this when you need to work with a different org, sandbox, scratch org, or production environment.
- Identifies and lists authenticated Salesforce orgs if needed
- Sets the default target org locally (within current project) or globally (system-wide)
- Verifies the org switch with configuration confirmation
- Handles both org usernames and aliases
- Detects and reports environment variable overrides that may prevent switching
How to install switching-org
npx skills add https://github.com/forcedotcom/sf-skills --skill switching-org- Salesforce CLI (sf) v2 or later installed
- At least one authenticated Salesforce org via `sf org login web`
How to use switching-org
- 1.Run `sf org list` to view all authenticated orgs if you don't know the org identifier
- 2.Provide the org username or alias you want to switch to
- 3.Run `sf config set target-org <orgIdentifier>` for local scope (current project) or add `--global` for system-wide scope
- 4.Verify with `sf config get target-org` to confirm the switch succeeded
Use cases
- Switch from a sandbox to production org for deployment
- Change to a scratch org for development work
- Point CLI commands to a different team member's org
- Set a global default org when working outside a project directory
- Verify which org is currently active before running commands
- Salesforce developers
- DevOps engineers managing multiple orgs
- Salesforce administrators
- Teams working with multiple environments
switching-org FAQ
Local scope (default) applies only within the current project directory. Global scope applies system-wide across all directories. Use local for normal project work; use global only when explicitly requested or when working outside a project.
Check whether the `SF_TARGET_ORG` environment variable is set — environment variables override config values. Unset it if it's blocking your switch.
No. The unified Salesforce CLI (sf) v2+ uses `target-org` and `target-dev-hub`. Legacy keys are deprecated.
Run `sf org list` to display all authenticated orgs with their usernames and aliases, then choose one to switch to.
The switch will fail. Run `sf org login web` to authenticate the org first, then retry the switch.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: switching-org description: "Switches the active Salesforce org (default target-org) using the Salesforce CLI. Use whenever someone wants to change which org CLI commands run against — whether they say "switch org", "change default org", "set my org to", "use alias", "point to", or describe wanting to work against a specific org, scratch org, sandbox, or production." compatibility: Salesforce CLI (sf) v2+ metadata: version: "1.0"
Steps
- Identify the org: the user provides a username or alias (
orgIdentifier). If not provided, runsf org listto show authenticated orgs and ask the user which one to use. - Set the default org:
- Local (default):
sf config set target-org <orgIdentifier>- Applies only within the current project directory. Use this for normal project work.
- Global (only if user explicitly requests):
sf config set target-org <orgIdentifier> --global- Applies system-wide across all directories. Use when working outside a project or when the user asks for global scope.
- If this fails, report the error and suggest running
sf org login webif the org may not be authorized.
- Local (default):
- Verify:
sf config get target-org --json- Note: the JSON output does not include a scope/location field — it cannot confirm whether the value is local or global. Confirm the value only, e.g.:
target-org is now set to: <value> - If it fails, report the error and advise running
sf config get target-org.
Notes
- Unified CLI uses keys like
target-organdtarget-dev-hub. Legacy sfdx keys (defaultusername,defaultdevhubusername) are deprecated in this context. - The sf CLI does not have
--localor--scopeflags for config set. Local scope is the default behavior. - If the org does not change after setting the config, check whether
SF_TARGET_ORGis set — environment variables override config values. - Salesforce CLI config (unified) reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_config_commands_unified.htm#cli_reference_config_set_unified
Related skills
More from forcedotcom/sf-skills and the wider catalog.

