Part of the Salesforce Admin Git & sf CLI series. Articles are standalone; read in any order. Foundation: Why Version Control · Environment Setup · Connect Your Org
TL;DR
- Connect to production:
sf org login web --alias prod(opens your browser, log in, done) - Connect to a sandbox:
sf org login web --instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com --alias sandbox. The--instance-urlflag is required for sandboxes - Always use
--alias: gives your org a short memorable name you type instead of a full username - Verify the connection:
sf org listshows all connected orgs;sf org display --target-org aliasshows details for one
What You'll Learn
- How to connect sf CLI to a production org
- How to connect sf CLI to a sandbox
- What an org alias is and why you should use one
- How to list connected orgs and check connection details
- How to set a default org so you don't need to type it every time
The Problem
You've installed sf CLI. Now what?
sf CLI is a powerful tool, but it doesn't automatically know which Salesforce org you want to work with. It can't touch your org until you give it permission. That permission process is called authentication, and it happens once per org. After that, sf CLI remembers the connection and you never have to log in again (unless the session expires or you revoke it).
This article shows you how to authenticate, how to handle sandboxes vs production, and how to verify everything is working before you run your first metadata command.
Common questions this article answers:
- How do I log in to Salesforce from the command line?
- What's the difference between production and sandbox login?
- What is an org alias in sf CLI?
- How do I check which orgs I've connected?
- How do I set a default org?
These commands work identically on Windows and macOS. sf CLI is cross-platform, so you can follow along on either machine.
Quick Answer
Here are all the essential commands in one place. The sections below explain each one in detail.
# Connect to a production org (with alias — strongly recommended)
sf org login web --alias prod
# Connect to a sandbox (--instance-url is required for sandboxes)
sf org login web --instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com --alias sandbox
# List all connected orgs
sf org list
# Show details for a specific org
sf org display --target-org prod
# Set a default org (so you don't need --target-org on every command)
sf config set target-org prod
# Check what your current default org is
sf config get target-org
How sf CLI Authentication Works
When you run sf org login web, sf CLI opens a browser window and sends you to the Salesforce login page. You log in there with your Salesforce username and password, or SSO, exactly as you normally would, and Salesforce grants sf CLI an OAuth access token.
Three things worth knowing about this flow:
Your password never goes in the terminal. You authenticate in the browser, same as logging in to any other app. sf CLI never sees your password.
sf CLI stores an access token, not credentials. After you log in, Salesforce issues a token that sf CLI saves to your local keychain (macOS Keychain or Windows Credential Manager). Future commands use that token. If you want to see what's stored, sf org display --target-org alias shows the token details.
This is standard OAuth, nothing unusual. It's the same flow as connecting Slack or a data loader to Salesforce. You're authorising an application (sf CLI) to act on your behalf. You can revoke that access at any time from Salesforce Setup → Connected Apps OAuth Usage.
Connect to a Production Org
# Basic login — opens your browser for OAuth
sf org login web
# With an alias — strongly recommended
sf org login web --alias prod
Running this command:
- Opens your default browser to the Salesforce login page
- You log in with your Salesforce credentials in the browser
- Salesforce redirects back to sf CLI, which captures the access token
- The terminal shows a success message with your org username
The --alias flag assigns a short name to this org. Without it, you would need to type your full Salesforce username ([email protected]) every time you reference this org in a command. With --alias prod, you type prod instead.
Good alias names are short and descriptive: prod, my-company-prod, acme-prod. Avoid spaces.
After login you'll see something like:
Successfully authorized [email protected] with org ID 00D...
You may now close the browser.
The browser tab will say "You may now close the browser". That's the expected end of the flow. Switch back to your terminal.
Connect to a Sandbox
# Login to a sandbox
sf org login web --instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com
# With alias — even more important for sandboxes since you'll typically have several
sf org login web --instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com --alias sandbox
The --instance-url flag tells sf CLI which Salesforce login page to use. Without it, sf CLI defaults to login.salesforce.com, the production login URL. Sandboxes use a different URL, and since My Domain became mandatory (Spring '21), that URL is org-specific, not the old generic test.salesforce.com. If you try to log in to a sandbox without this flag, the production login page opens and your sandbox credentials won't work (or worse, you'll accidentally log in to the wrong org).
Your sandbox URL: Replace
<MyDomain>with your company's My Domain name and<SandboxName>with the sandbox name. You can find this URL by logging into your sandbox via the browser. It appears in the address bar. Example: if your company is Acme and your sandbox is nameddev, the URL ishttps://acme--dev.sandbox.my.salesforce.com.
If you have multiple sandboxes (say a developer sandbox and a UAT sandbox), connect each one with a different alias:
# Connect developer sandbox
sf org login web --instance-url https://<MyDomain>--dev.sandbox.my.salesforce.com --alias dev-sandbox
# Connect UAT sandbox
sf org login web --instance-url https://<MyDomain>--uat.sandbox.my.salesforce.com --alias uat-sandbox
Both orgs will appear in sf org list and you pick which one to target per command.
Production org with My Domain? If your production org uses a custom login URL (e.g.,
https://mycompany.my.salesforce.com), use that as--instance-urlinstead:sf org login web --instance-url https://mycompany.my.salesforce.com --alias prodSandbox URLs always use the
--sandboxnameformat shown above and are separate from production My Domain URLs.
List Your Connected Orgs
# Show all connected orgs
sf org list
# Show details for one specific org
sf org display --target-org prod
# Show details using the full username instead of alias
sf org display --target-org [email protected]
sf org list gives you an overview of every org sf CLI knows about. A typical output looks like this:
=== Non-scratch orgs
ALIAS USERNAME ORG ID CONNECTED STATUS
──────────── ─────────────────────────── ────────────────── ────────────────
prod [email protected] 00D... Connected
sandbox [email protected] 00D... Connected
sf org display --target-org prod gives you the full details for a single org:
=== Org Description
KEY VALUE
──────────────── ──────────────────────────────────────────
Access Token <session-token>
Alias prod
Client Id PlatformCLI
Connected Status Connected
Id 00D...
Instance Url https://yourorg.lightning.force.com
Username [email protected]
The Connected Status: Connected line is what you're looking for. If it says Connected, sf CLI can reach the org and the token is valid. If it shows anything else, see the Troubleshooting section below.
Set a Default Org
Every sf CLI command that touches an org requires you to specify which org. You can do this explicitly on each command with --target-org alias, or you can set a default org so sf CLI uses it automatically.
# Set your default org
sf config set target-org prod
# Check what the current default org is
sf config get target-org
# Remove the default (go back to requiring --target-org explicitly)
sf config unset target-org
Once you've set a default org, commands like this work without any extra flag:
# Without a default org — you must specify --target-org every time
sf project retrieve start --metadata Flow --target-org prod
# With a default org set — sf CLI knows which org to use
sf project retrieve start --metadata Flow
The default org setting is stored per project (in the .sf/config.json file inside your project folder) when you run sf config set from within a project directory. Run it from outside a project and it sets a global default.
For most admins working primarily with one org, setting a default saves a lot of typing.
Verify Your Connection
Before running any metadata commands, confirm the connection is working.
# Quick connection test — fetches org info and confirms the token is valid
sf org display --target-org prod
# Alternatively — if your org appears in this list, the connection is working
sf org list
A successful sf org display output shows Connected Status: Connected. That means:
- sf CLI can reach the org
- The OAuth token is still valid
- You're ready to retrieve and deploy metadata
If the status shows anything other than Connected, or if the command errors, see the Troubleshooting section.
Troubleshooting
"No default org set" error
Error (1): No default target org is set and you did not specify the --target-org flag.
You haven't set a default org, and the command you ran needs to know which org to target. Fix it one of two ways:
- Add
--target-org aliasto your command:sf project retrieve start --metadata Flow --target-org prod - Set a default org:
sf config set target-org prod
Browser doesn't open
If the browser window doesn't open when you run sf org login web, force a specific browser with the --browser flag:
# Force Chrome
sf org login web --browser chrome --alias prod
# Force Firefox
sf org login web --browser firefox --alias prod
Valid browser values are chrome, edge, and firefox.
Fallback: If no browser opens and the flag doesn't help, sf CLI will print a URL in the terminal. Copy and paste that URL into your browser manually to complete the OAuth flow.
Login URL error / wrong org type
If you land on the production login page but you're trying to log in to a sandbox (or vice versa), the credentials won't work. Double-check which flag to use:
- Production org: no
--instance-urlflag needed (or usehttps://login.salesforce.com) - Sandbox:
--instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.comis required - Custom domain:
--instance-url https://yourcompany.my.salesforce.com
"Org not found" after login
If you get an error saying the org can't be found, run sf org list to see what sf CLI actually stored. The alias or username might differ from what you expect. Use the exact value shown in the list.
Session expired or token revoked
If commands that used to work start throwing authentication errors, the token may have expired or been revoked in Salesforce. Re-run the login with the same alias to refresh:
# Re-authenticate using the same alias — overwrites the old token
sf org login web --alias prod
Using the same --alias replaces the stored token without creating a duplicate entry.
Frequently Asked Questions
Q: Can I connect multiple orgs at the same time?
Yes. Run sf org login web once per org, each time with a different --alias. All connected orgs show up in sf org list and you pick which one to use per command with --target-org, or set a default with sf config set target-org.
Q: What is an org alias and do I need one?
An alias is a short name you assign to a connected org (prod, sandbox-dev, uat) so you don't have to type the full username every time. You don't technically need one; you can always use the full username (e.g., [email protected]) in place of an alias. But aliases are much easier to type and much less likely to contain typos when you're running many commands.
Q: What's the difference between production and sandbox login?
Production orgs use login.salesforce.com as their login URL, which is sf CLI's default. Sandboxes use an org-specific URL in the format https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com. sf CLI defaults to the production URL, so sandbox users must pass the correct --instance-url to be routed to the right login page.
Q: Where does sf CLI store my credentials?
sf CLI stores an OAuth access token (not your password) in your local system credential store. On macOS this is the system Keychain; on Windows it uses the Windows Credential Manager. Your actual password is never stored anywhere by sf CLI. You can inspect the stored auth details (without the token value) with sf org display --target-org alias.
Q: What if I have a custom domain (My Domain)?
If your org uses a custom login domain (for example, https://mycompany.my.salesforce.com), pass that as the --instance-url:
sf org login web --instance-url https://mycompany.my.salesforce.com --alias prod
Sandbox My Domain URLs always include the --<SandboxName>.sandbox segment and are structurally different from production My Domain URLs. They are not interchangeable.
Q: Can I connect to a Developer Edition org?
Yes. Developer Edition orgs use the production login URL (login.salesforce.com), the same as regular production orgs. No special flag needed:
sf org login web --alias dev-edition
Key Takeaways
- Browser OAuth only:
sf org login webopens a browser for secure OAuth. Your password never goes in the terminal - Sandbox requires --instance-url: Sandbox orgs require
--instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com. Without it, sf CLI tries the production login URL - Always alias your orgs: Always use
--alias. A memorable short name saves typing on every future command - List and inspect connections:
sf org listshows all connected orgs;sf org display --target-org aliasshows full details including connection status - Set a default org:
sf config set target-org aliassets a default org so you don't need--target-orgon every command - Refresh expired tokens: Re-run
sf org login web --alias same-aliasto refresh an expired token without creating a duplicate
What's Next?
With your org connected, sf CLI can now fetch your metadata (Flows, Objects, Profiles, Page Layouts, and more) directly from Salesforce into files on your machine. That's where version control becomes genuinely useful.
Recommended Reading (this series):
- Article 4: Fetching Custom Configuration Metadata: CustomObject, CustomField, Layout, FlexiPage
- Article 5: Fetching Automation Metadata: Flow, WorkflowRule, ApprovalProcess
- Article 10: Git Basics for Salesforce Admins: Track Your Org Changes
Action Items:
- Run
sf org login web --alias prodright now and complete the browser OAuth flow - If you have a sandbox, connect it:
sf org login web --instance-url https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com --alias sandbox - Run
sf org listto confirm both orgs appear - Set your most-used org as default:
sf config set target-org prod - Run
sf org display --target-org prodand confirmConnected Status: Connected
Resources & References
- Salesforce sf CLI Command Reference: sf org login web
- sf CLI Installation Guide
- Salesforce OAuth 2.0 Web Server Flow
About This Guide: Part of the Salesforce Admin Git & sf CLI series, a complete guide to version control for Salesforce admins. Each article stands alone but links to related articles throughout the series.
Tags: #salesforce #sfcli #versioncontrol #salesforceadmin