Skill

Pass

Audit score 90

dx-org-switch

forcedotcom/sf-skills

Switch the active Salesforce org for CLI commands using the Salesforce CLI.

What is dx-org-switch?

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.

Identify and list authenticated Salesforce orgs if needed
Set the default target org locally (project-scoped) or globally (system-wide)
Verify the active org configuration
Handle org switching for scratch orgs, sandboxes, and production environments
Report errors and suggest troubleshooting steps like re-authenticating with sf org login web

How to install dx-org-switch

npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-switch

Prerequisites

Salesforce CLI (sf) version 2.0.0 or later installed
At least one authenticated Salesforce org via sf org login web or similar

Claude Code

Cursor

Windsurf

Cline

How to use dx-org-switch

1.Provide the org username or alias, or run sf org list to see available authenticated orgs
2.Choose local scope (default, project-scoped) or global scope (system-wide) based on your needs
3.Run sf config set target-org <orgIdentifier> for local or sf config set target-org <orgIdentifier> --global for system-wide
4.Verify the change with sf config get target-org --json
5.If the org does not change, check whether SF_TARGET_ORG environment variable is set, as it overrides config values

Use cases

Good for

Switch between multiple scratch orgs during development
Change from a sandbox to production for deployment tasks
Set a dev hub as the default org for org creation commands
Work with different client or project orgs without re-authenticating
Override the active org when environment variables are not set

Who it's for

Salesforce developers using the Salesforce CLI
DevOps engineers managing multiple Salesforce environments
Developers working with scratch orgs and sandboxes

dx-org-switch FAQ

What is the difference between local and global scope?

Local scope (default) applies the org switch only within the current project directory. Global scope applies system-wide across all directories and is used when working outside a project or when explicitly requested.

What if the org does not appear in sf org list?

The org may not be authenticated. Run sf org login web to authenticate the org, then try switching to it.

Why did the org not change after running the config command?

The SF_TARGET_ORG environment variable may be set, which overrides config values. Check and unset it if needed, or verify the config with sf config get target-org.

Can I use legacy sfdx keys like defaultusername?

No, the unified Salesforce CLI uses target-org and target-dev-hub. Legacy keys are deprecated.

How do I verify which org is currently active?

Run sf config get target-org --json to check the current default target org.

Full instructions (SKILL.md)

Source of truth, from forcedotcom/sf-skills.

name: dx-org-switch 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." metadata: version: "1.0" domains: ["Developer Experience"] cliTools: - tool: ["sf"] semver: ">=2.0.0"

Steps

Identify the org: the user provides a username or alias (orgIdentifier). If not provided, run sf org list to 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 web if the org may not be authorized.
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-org and target-dev-hub. Legacy sfdx keys (defaultusername, defaultdevhubusername) are deprecated in this context.
The sf CLI does not have --local or --scope flags for config set. Local scope is the default behavior.
If the org does not change after setting the config, check whether SF_TARGET_ORG is 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.

dx-org-trial-expiration-check

forcedotcom/sf-skills

Check Salesforce org trial expiration dates and days remaining across one or all authenticated orgs.

3.0k installsAudited

dx-pkg-post-install-configure

forcedotcom/sf-skills

Automate post-install configuration for any Salesforce managed package.

3.5k installs

dx-project-create

forcedotcom/sf-skills

Scaffold a new Salesforce DX project with any template and configure it end-to-end.

2.4k installsAudited

experience-aura-lwc-migrate

forcedotcom/sf-skills

Analyze Salesforce Aura components and generate framework-agnostic migration blueprints (PRDs) for LWC conversion.

1.8k installs

experience-cms-brand-apply

forcedotcom/sf-skills

Search, extract, and apply Salesforce CMS brand guidelines to generated content.

4.9k installs

experience-content-media-search

forcedotcom/sf-skills

Search and retrieve existing visual media from Salesforce CMS, Data 360, and connected sources.

4.8k installs