Building modern, headless digital experiences with Sitecore often begins with a single command: installing the Sitecore JSS CLI. This powerful tool is the gateway to creating JSS applications, managing deployments, and interacting with your Sitecore instance from your local machine. However, many developers encounter a frustrating roadblock immediately after installation: the system claims the 'jss' command does not exist.
If you have just run the installation command and received a message stating "The term 'jss' is not recognized as the name of a cmdlet, function, script file, or operable program," you aren't alone. This is one of the most common configuration hurdles in the Sitecore Headless ecosystem. In this guide, you will learn exactly why this happens and how to resolve it permanently so you can get back to building your application.
Understanding the 'jss' Command Recognition Error
When you install the Sitecore JSS CLI using npm, you are essentially downloading a package of Node.js scripts. For your operating system to execute these scripts simply by typing jss, it needs to know exactly where those scripts live on your hard drive.
This "knowledge" is stored in a system setting called the Path Environment Variable. If the installation path for npm global modules is missing from this variable, Windows will search the standard locations, fail to find the JSS executable, and throw the error you are seeing.
Before diving into complex fixes, it is important to understand that seeing warnings during the installation process—specifically regarding fsevents—is usually normal. You might see a log like this:
npm install -g @sitecore-jss/sitecore-jss-cli
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected]
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
These warnings occur because fsevents is a macOS-specific dependency. If you are on Windows, npm correctly skips it. This does not mean your installation failed; it simply means your environment needs a few manual tweaks to recognize the new command.
Step 1: Verify the Global Installation
The first step is ensuring that you actually installed the CLI globally. If you omit the -g flag, the JSS CLI is installed only in the current folder's node_modules directory, meaning it won't be available as a system-wide command.
Run the following command in your terminal to ensure a fresh, global installation:
npm install -g @sitecore-jss/sitecore-jss-cli
Pay close attention to the output path provided by npm. It will usually look something like C:\Users\<YourUser>\AppData\Roaming\npm\jss. This path is the critical piece of information we need for the next steps.
Step 2: Refreshing Your Terminal Environment
Before modifying system settings, try the simplest fix: restart your terminal.
Command-line interfaces like PowerShell, CMD, and the integrated terminal in Visual Studio Code cache the list of available commands when they first open. If you install a new tool while the terminal is already running, that specific instance of the terminal may not "see" the new executable yet.
Close all instances of your terminal and VS Code, then reopen them and try running:
jss --help
If the error persists, the issue is almost certainly related to your Windows Environment Variables.
Step 3: Configuring Windows Environment Variables
To fix the "not recognized" error permanently, you must manually add the npm global folder to your Windows Path. This ensures that no matter where you are in your file system, Windows knows where to find the Sitecore JSS CLI.
How to Edit Your Path Variable
- Press Win + R on your keyboard to open the Run dialog.
- Type the following command and press Enter:
rundll32 sysdm.cpl,EditEnvironmentVariables - In the User variables section (the top box), look for a variable named Path.
- Select Path and click Edit....
- Check if the npm global directory is listed. On most modern Windows installations, this is:
%AppData%\npm - If you do not see that entry, click New and paste in
%AppData%\npm. - Click OK on all three dialog boxes to save your changes.
Note: If you have customized your npm configuration to install global packages elsewhere, you should use that specific path instead of the default %AppData% location.
Step 4: Verification and Version Context
Once you have updated the Path variable, you must restart your terminal for the changes to take effect. Open a new PowerShell window and type:
jss --version
If you see a version number (e.g., 21.6.0), your installation is successful.
As Sitecore evolves, the JSS CLI undergoes frequent updates. While the core installation method remains the same, always ensure your CLI version matches the version of Sitecore JSS you intend to use in your project. Using a very old CLI with a newer Sitecore Headless instance (or vice versa) can lead to unexpected errors during the jss setup or jss deploy phases.
Frequently Asked Questions
Why did the JSS installation work on one machine but not another?
This is typically due to how Node.js was originally installed. Some installers automatically add the npm path to the Windows Environment Variables, while others (or specific security policies on corporate VMs) may skip this step, requiring manual intervention.
Can I use the JSS CLI without installing it globally?
Yes. You can use npx @sitecore-jss/sitecore-jss-cli <command> to run JSS commands without a global installation. However, for a smoother developer experience and to follow standard Sitecore documentation, a global installation is highly recommended.
Does this fix apply to other CLI tools like the Sitecore CLI?
Yes! The principle is the same. Whether you are working with the Sitecore JSS CLI or the Sitecore Serialization CLI (dotnet sitecore), if the command is not recognized, it is almost always because the executable's directory is missing from your system's Path variable.
Wrapping Up
Setting up a Sitecore JSS development environment is an exciting step toward modern headless development. While the "jss is not recognized" error can feel like a setback, it is simply a matter of aligning your Windows configuration with your Node.js environment. By ensuring your global npm path is correctly set in your Environment Variables and restarting your terminal, you clear the way for a productive development workflow.
Now that your CLI is ready, you can move forward with creating your first project using jss init and exploring the power of Sitecore Headless!