Setting Up Your Environment: Terminal, sf CLI, and Git for Salesforce Admins

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

• Terminal: Already on your machine (Command Prompt or PowerShell on Windows, Terminal on macOS)
• sf CLI: Install via npm install -g @salesforce/cli or download the standalone .exe / .pkg installer from Salesforce
• Git: Download from git-scm.com (Windows) or run xcode-select --install (macOS)
• Verify both: sf --version and git --version. If both print version numbers, you're done

What You'll Learn

• What a terminal is and how to open one on your machine
• How to install sf CLI (the official Salesforce command-line tool) on Windows and macOS
• How to install Git on Windows and macOS
• How to create a Salesforce project folder and initialise it with sf template generate project
• How to fix the most common installation errors before you waste 30 minutes on them

The Problem

Salesforce admins increasingly need to work outside the browser: retrieving metadata, deploying to sandboxes, and tracking changes with version control. Before any of that is possible, three things need to be on your machine: a terminal to type commands into, sf CLI to talk to Salesforce, and Git to track your work.

Common Questions This Article Answers:

• What even is a terminal, and which one should I use?
• Do I install sfdx or sf? They look the same.
• What's the difference between the npm install and the standalone installer?
• Why does my machine say "sf is not recognized" after installing?
• Do I really need Git just to work with metadata?

Quick Answer

Run these four commands after installing everything. If each one prints a version number without an error, your environment is ready.

# Verify sf CLI
sf --version

# Verify Git
git --version

# Verify Node.js (needed for npm install method)
node --version

# Verify npm
npm --version

Expected output (versions will vary; any recent version is fine):

@salesforce/cli/2.135.7 darwin-arm64 node-v22.14.0
git version 2.49.0
v22.14.0
10.9.2

What Is a Terminal?

A terminal (also called a command prompt, shell, or console) is a text window where you type commands and the computer runs them. Everything you do through a GUI (opening files, connecting to servers, running programs) can be done through a terminal. For Salesforce work, you will use it to run sf and git commands.

Opening a Terminal on Windows

Option 1: Command Prompt Press Win + R, type cmd, press Enter. The simplest option; works for all commands in this guide.

Option 2: PowerShell Press Win + X, then click "Windows PowerShell" or "Terminal". More powerful than Command Prompt and the better long-term choice.

Option 3: Windows Terminal (Recommended) Download Windows Terminal from the Microsoft Store (it's free). It runs PowerShell, Command Prompt, and Git Bash in tabs and is the best experience on Windows.

Opening a Terminal on macOS

Option 1: Terminal (built-in) Press Cmd + Space, type "Terminal", press Enter. It's already installed.

Option 2: iTerm2 (popular alternative) Download from iterm2.com. Not required, but many developers prefer it for split panes and better colour support.

For everything in this guide, the built-in Terminal is completely sufficient.

Installing sf CLI

Salesforce CLI (sf) is the official tool for working with your Salesforce org from the command line: authenticating, deploying, retrieving metadata, running tests, and more. It replaced the older sfdx CLI; if you have sfdx-cli installed from an old tutorial, uninstall it first (it will block sf).

There are two install paths: the standalone installer (no prerequisites, click through a wizard) or npm (requires Node.js, but keeps the CLI easily updatable).

Windows: Standalone Installer

The standalone installer is the easiest route if you have never installed Node.js.

Step 1: Download the installer

Go to developer.salesforce.com/tools/salesforcecli and download the Windows installer. Two versions are available:

• Windows x64: use this for most machines
• Windows ARM64: use this only if you have an ARM-based Windows device (e.g., some Surface Pro models)

Direct download links (these pull the latest stable release):

• x64: https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-x64.exe
• ARM64: https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-arm64.exe

Step 2: Run the installer

Double-click the .exe and follow the wizard. Accept the defaults. The installer adds sf to your PATH automatically.

Step 3: Open a new terminal and verify

sf --version

You should see something like:

@salesforce/cli/2.135.7 win32-x64 node-v22.14.0

Windows: npm Method

Use this method if you already have Node.js installed or want to manage the CLI version alongside other Node.js tools.

Step 1: Install Node.js

Download the LTS version from nodejs.org. Install with defaults. This also installs npm automatically.

Step 2: Verify Node.js and npm

node --version
npm --version

You need Node.js 22 or 24 (both are supported LTS versions).

Step 3: Install sf CLI globally

npm install -g @salesforce/cli

The -g flag means "install globally": available from any folder on your machine, not just the current one.

Step 4: Verify

sf --version

macOS: npm Method (Recommended)

Step 1: Install Node.js

Download the LTS installer from nodejs.org, or if you use Homebrew:

brew install node

Step 2: Install sf CLI globally

npm install -g @salesforce/cli

Step 3: Verify

sf --version

macOS: Homebrew Method

If you already have Homebrew installed:

brew install sf

Homebrew installs a tap maintained by Salesforce. Update it later with:

brew upgrade sf

macOS: Standalone Installer

Go to developer.salesforce.com/tools/salesforcecli and download the macOS package. Two versions:

• Apple Silicon (M1/M2/M3/M4): sf-arm64.pkg
• Intel CPU: sf-x64.pkg

Double-click the .pkg file and follow the installer. Open a new terminal and run sf --version to verify.

Keeping sf CLI Updated

# npm method — update to latest
npm update -g @salesforce/cli

# Homebrew method
brew upgrade sf

# Check current version any time
sf --version

Installing Git

Git is version control software that tracks every change you make to your metadata files. Even if you never use GitHub or a remote repository, Git is required by the Salesforce project structure and by most CI/CD pipelines you will eventually encounter.

Windows: Git for Windows

Step 1: Download the installer

Go to git-scm.com/download/win. The download starts automatically for your architecture.

Step 2: Run the installer

The installer has many screens. The defaults are fine for most admins. One setting worth changing:

• On the "Choosing the default editor" screen, switch from Vim to "Notepad" or "Visual Studio Code" if you have VS Code installed. This affects the editor that opens when Git needs you to type a commit message.

Accept all other defaults and finish the installation.

Step 3: Open a new terminal and verify

git --version

Expected output:

git version 2.49.0.windows.1

macOS: Xcode Command Line Tools (Easiest)

You may already have Git. Open Terminal and run:

git --version

If Git is not installed, macOS will automatically prompt you to install the Xcode Command Line Tools. Click Install and wait. It takes a few minutes. Once done, git --version will return a version number.

You can also trigger the install manually:

xcode-select --install

macOS: Homebrew (Recommended for Newer Versions)

The Xcode Command Line Tools version of Git tends to lag behind the latest release. If you want the current version:

brew install git

Update later with:

brew upgrade git

Verify Git Installation

git --version

Expected output on macOS:

git version 2.49.0

Configure Git with Your Name and Email

Before using Git, tell it who you are. These details appear on every commit you make:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Replace the values with your actual name and email. This is a one-time setup per machine.

Setting Up Your Project Folder

With sf CLI and Git installed, create a Salesforce project. This sets up the folder structure that sf CLI and Salesforce expect, including the force-app directory where your metadata lives.

Step 1: Create and enter your project folder

# Windows (PowerShell or Command Prompt)
mkdir my-salesforce-project
cd my-salesforce-project

# macOS (Terminal)
mkdir my-salesforce-project
cd my-salesforce-project

Replace my-salesforce-project with whatever you want to name your project.

Step 2: Generate the project

sf template generate project --name my-salesforce-project --default-package-dir force-app

Note: Older tutorials use sf project generate. That command still works but prints a deprecation warning. The current command is sf template generate project. Both do the same thing; use the one above to avoid the warning.

What these flags do:

• --name my-salesforce-project: sets the project name in the generated config file
• --default-package-dir force-app: creates a force-app folder as the default location for your metadata. This is the Salesforce convention; most tutorials and CI tools expect this name.

Step 3: See what was created

# Windows
dir

# macOS
ls -la

You will see:

force-app/
.forceignore
.gitignore
sfdx-project.json

• force-app/: where your metadata (flows, profiles, objects, etc.) will live
• sfdx-project.json: the project config file sf CLI reads
• .gitignore: tells Git which files to ignore (already pre-populated with sensible defaults)
• .forceignore: tells sf CLI which files to skip when deploying

Step 4: Initialise Git

git init
git add .
git commit -m "initial project setup"

git init creates a hidden .git folder (the Git repository). git add . stages all files. git commit saves the first snapshot.

Troubleshooting

"sf is not recognized" / "sf: command not found"

This means sf CLI is not on your PATH. Either the installation failed silently, or the terminal was open during installation and has a stale PATH.

Fix 1: Close and reopen your terminal. Always do this after any installation. PATH changes only take effect in new terminal sessions.

Fix 2 (Windows): Check the installation succeeded

where sf

If this prints a path, sf is installed. Close and reopen your terminal. If it prints nothing, reinstall.

Fix 3 (macOS): Check the installation succeeded

which sf

If blank, the install failed or npm's global bin directory is not on your PATH. Run:

npm root -g

This shows where npm installs global packages. The bin folder one level up needs to be in your PATH.

Fix 4 (macOS npm permission error during install):

If npm install -g @salesforce/cli throws a permission error, do not use sudo npm install. Instead, fix npm's permissions or use nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Restart terminal, then install Node via nvm
nvm install --lts

# Now install sf CLI without permission issues
npm install -g @salesforce/cli

"git is not recognized" / "git: command not found"

Windows: Close and reopen your terminal after installing Git for Windows. If still not found, search "Environment Variables" in the Start menu, open "System Environment Variables", find PATH, and check that the Git bin directory (C:\Program Files\Git\cmd) is listed.

macOS: Run xcode-select --install. Even if you installed via Homebrew, the Xcode Command Line Tools sometimes need to be present for Git to work fully.

"npm is not installed" / "npm: command not found"

npm comes bundled with Node.js. If npm is not found, Node.js either was not installed or was not added to PATH.

Download the LTS installer from nodejs.org, run it, close and reopen your terminal, then try node --version and npm --version.

"You have sfdx-cli installed" warning

The old sfdx-cli package conflicts with @salesforce/cli. Uninstall it first:

npm uninstall -g sfdx-cli

Then install sf CLI:

npm install -g @salesforce/cli

sf version output looks different from what you expect

sf --version output includes the CLI version, your OS, and the Node.js version used internally:

@salesforce/cli/2.135.7 darwin-arm64 node-v22.14.0

The version numbers will differ from what you see here. That is normal. As long as the command runs and prints something, the install worked. If the major version is 2.x.x, you have the current sf CLI.

Frequently Asked Questions

Q: What is the difference between sfdx and sf?

sfdx was the original Salesforce CLI, released in 2017. sf is the v2 unified CLI that replaced it in 2023. They are now the same tool. sf is the one you should use. Many older tutorials still reference sfdx commands; most of those commands now have sf equivalents. If you see sfdx force:source:push, the current equivalent is sf project deploy start.

Q: Do I need to install Node.js if I use the standalone installer?

No. The standalone .exe (Windows) and .pkg (macOS) installers bundle Node.js. You get everything you need in one download. You only need to install Node.js separately if you choose the npm installation method.

Q: Can I use a different folder name instead of force-app?

Yes, but force-app is the default convention and what every tutorial, template, and CI pipeline expects. Changing it requires updating sfdx-project.json and can cause confusion. Stick with force-app unless you have a specific reason.

Q: Do I need a Salesforce org to complete this setup?

No. Installing sf CLI, Git, and creating a project folder does not require an org connection. You can complete this entire article offline. Connecting to an actual org is covered in Article 3.

Q: Is Salesforce CLI free?

Yes. sf CLI is free, open source, and maintained by Salesforce. You can find the source code at github.com/salesforcecli/cli.

Q: What version of Node.js do I need?

Salesforce CLI supports Node.js 22 (Maintenance LTS) and Node.js 24 (Active LTS). Node.js 18 reached end-of-life in April 2025 and is no longer supported. If you are on an older version, update before installing sf CLI.

Key Takeaways

• A terminal is just a text window. You already have one on your machine
• sf CLI (@salesforce/cli) is the current tool; sfdx-cli is deprecated and should be removed if present
• Two install paths for sf CLI: standalone installer (easiest, no prerequisites) or npm (requires Node.js, easier to update)
• sf --version and git --version are your confirmation that everything worked
• sf template generate project --name your-project --default-package-dir force-app sets up the correct folder structure for Salesforce metadata
• Always close and reopen your terminal after installing anything. PATH changes only apply to new sessions
• "Not recognized" errors almost always mean PATH, not a broken installation

What's Next?

With your terminal, sf CLI, and Git in place, the next step is connecting sf CLI to an actual Salesforce org. Article 3 covers authorising to a sandbox or production org, listing your connected orgs, and running your first metadata retrieve.

Connect Your Org with sf CLI →

Resources & References

• Salesforce CLI Download Page: standalone installers for Windows and macOS
• Salesforce CLI npm Package: @salesforce/cli on npm
• Salesforce CLI Setup Guide (official docs)
• Git for Windows
• Git for macOS
• Node.js LTS Releases: check supported versions
• nvm (Node Version Manager for macOS/Linux)
• nvm-windows: Node Version Manager for Windows
• Windows Terminal: free, from the Microsoft Store