dx-org-switch — Claude Code skill: switch the active Salesforce org
Switches the active Salesforce org via sf config set target-org. Useful when CLI commands keep hitting the wrong org.
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a claude-codeWhat dx-org-switch does
The skill figures out which org you want as the default and writes it to target-org. No username or alias given? The agent runs sf org list, shows the authenticated orgs and asks which one to use. Then it sets sf config set target-org <orgIdentifier>, scoped to the current project directory by default. Global scope only happens if you ask for it, with --global.
Verification comes next: sf config get target-org --json. One catch — that JSON has no scope field, so the skill can confirm the value but not whether it is local or global. If the command fails, it reports the error and suggests sf org login web when the org may not be authorized.
Keep one more thing in mind: the SF_TARGET_ORG environment variable overrides config values. Set a new org and commands still go to the old one? Check that variable first. Legacy keys defaultusername and defaultdevhubusername are deprecated here; the unified CLI uses target-org and target-dev-hub. You need sf 2.0.0 or newer.
What it helps with
- point CLI commands at a different org without editing config by hand
- list authenticated orgs and pick one as the default
- set the default org for the current project only
- debug why commands still run against the old org
- check the current
target-orgvalue
Example prompts for the agent
- switch my org to the uat-sandbox alias
- list my authenticated orgs and set one as default
- set target-org globally to prod-alias
How to install dx-org-switch
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a claude-code2Manually: put the files in place
~/.claude/skills/dx-org-switch/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dx-org-switch/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a codex2Manually: put the files in place
.agents/skills/dx-org-switch/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a cursor2Manually: put the files in place
.cursor/skills/dx-org-switch/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install forcedotcom/sf-skills dx-org-switch2Manually: put the files in place
.github/skills/dx-org-switch/SKILL.md1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a gemini-cli2Platform CLI
gemini skills install https://github.com/forcedotcom/sf-skills --path skills/dx-org-switchManually: put the files in place
.devin/skills/dx-org-switch/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill dx-org-switch -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dx-org-switch
How do I install dx-org-switch in Claude?
Run npx skills add forcedotcom/sf-skills --skill dx-org-switch -a claude-code. The skill lands in ~/.claude/skills/dx-org-switch/SKILL.md.
What does dx-org-switch do?
It changes the active Salesforce org that CLI commands run against, using sf config set target-org. Without an org name it lists authenticated orgs first.
Why does the org not change after I set it?
Check SF_TARGET_ORG — environment variables override config values. If the org is not authorized, run sf org login web.
Source text
SKILL.md · Apache-2.0
---
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
1. 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.
2. 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.
3. 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
© forcedotcom · Apache-2.0 · forcedotcom/sf-skills
