Use this guide after installation and account sign-in. The goal is one working development connection, with the correct project, account, and code version
Have these details ready
- Your project repository, including the cartridges you work on
- The development sandbox hostname and intended code version
- Your sandbox account, or the team's encrypted credentials file and its matching secret key
- The site and cartridge path your team uses. API clients and certificates are needed only when your sandbox or chosen features require them
Open your project
Open the folder that holds your cartridges, usually the repository root. Any of these routes opens it:
| Route | macOS | Windows and Linux |
|---|---|---|
| File menu | File › Open... in the menu bar (⌘O). It opens folders as well as files | File › Open Folder... (Ctrl+K Ctrl+O). If the menu bar is collapsed into the ☰ icon at the top left, open that first |
| Explorer | In a window with no folder, open the Explorer (⇧⌘E) and select Open Folder | The same, the Explorer is Ctrl+Shift+E |
| Command Palette | ⇧⌘P, then File: Open Folder... | Ctrl+Shift+P, then File: Open Folder... |
Pick the folder and select Open. The first time VS Code opens a folder it asks Do you trust the authors of the files in this folder? Select Yes, I trust the authors. In restricted mode VS Code disables Intellij SFCC
Once the folder is open, Intellij SFCC recognizes the SFCC project by its cartridges or a dw.json that names a host, and opens Intellij SFCC: Getting Started. The status bar shows Setup 1/5, because the 7-day trial already counts as the first step
Use Getting Started
Getting Started opens in its own tab every time a window starts on an SFCC project whose setup is unfinished. It lists seven setup steps, then a short tour of the plugin. Five steps are tracked: Sign in, Add credentials, Add a connection, Link cartridges and Select B2C scope. Upload and deploy and Connect AI agents come last and are not counted
To come back to it, click Setup 3/5 at the right end of the status bar (its tooltip reads "Intellij SFCC setup: 3 of 5 steps done. Click to continue"), or open the Command Palette (⇧⌘P on macOS, Ctrl+Shift+P on Windows and Linux) and run Intellij SFCC: Getting Started. The tab opens on the first step that is not done yet. Once all five are done, the status bar item reads Setup
Tick Don't open automatically on the page when you only want it from the status bar. The same switch is the intellij-sfcc.gettingStarted.doNotOpenAutomatically setting. Tick Show only the panda in the status bar to drop the item's text. Its tooltip still shows the progress
Folders without SFCC code
In a folder with no cartridges, no dw.json and no connection, Intellij SFCC stays out of the way: no Setup item, no SFCC views, and Getting Started does not open. Cartridges in test or fixture folders do not count. Only Find Cartridges stays in the status bar. When it finds nothing, it offers Create Cartridge… and Set Up Anyway, which shows the setup in that folder from then on
Cartridges cloned or copied in while the window is open show the setup without a restart. Nothing hides again until the next start
VS Code's own Welcome page also lists the walkthrough Get started with Intellij SFCC, with two steps: Open the Intellij SFCC guide and Sign in or create an account. Your free 7-day trial starts when you install the plugin, so signing in is only needed for a plan you bought or a seat from your organization. Run Intellij SFCC: Open Getting Started Walkthrough to open it
Every step has a button that runs the real action:
- Sign in and Create account start the sign-in step, and Show Account panel opens the account view
- Add account opens the Credentials editor for your Business Manager login
- Add connection asks for the connection name, hostname, account and code version
- Find cartridges lists the cartridge folders in your project that are not linked yet
- Select B2C scope opens the site picker for the active connection
- Turn on auto upload sends every save to the active connection's code version, so check that connection and code version first
As soon as a step is done, the guide moves to the next one and the status bar count goes up
Learn the plugin
After the setup steps, the Learn the plugin group of the rail is a short tour. Back and Next move through it:
| Page | What it shows | Buttons |
|---|---|---|
| Status bar | The items the plugin adds to the status bar for the active connection | Focus status bar |
| Explorer menu | The B2C actions in the Explorer right-click menu | Show Explorer |
| Two-column layout | Moving Intellij SFCC to the Secondary Side Bar, with your files on the left. Shown when your editor has a Secondary Side Bar | Show Intellij SFCC, Open Secondary Side Bar |
| Log Center | Streaming and parsing instance logs into ranked issues linked to your code | Open Log Center, Full view |
| Documentation | Where every panel and command is documented | Open documentation |
Connect your project
To set up by hand, with a few extra checks for the first connection, follow these steps
Open the Intellij SFCC sidebar
Select the Intellij SFCC icon in the Activity Bar on the left, or run View: Show Intellij SFCC from the Command Palette (⇧⌘P on macOS, Ctrl+Shift+P on Windows and Linux). The sidebar holds the Explorer and Credentials sections used below. Your project folder must already be open, see Open your project
Add or link credentials
Expand Credentials in the sidebar. Until a file is linked it offers Create B2C Credentials File and Link existing B2C Credentials File. Create or link your credentials file, then add your Business Manager account with Add account in Getting Started or Intellij SFCC: Add Credentials Account in the Command Palette. Connection records reference these credentials
Passwords, access keys, and API client secrets stay in that encrypted file, never in a plain-text dw.json, so AI agents such as Codex and Claude Code that read your files find nothing usable. See Hidden From AI Agents
Create the sandbox connection
While Explorer in the Intellij SFCC sidebar is empty, it shows an Add B2C Connection button. The same command is the + in the section's title bar and Intellij SFCC: Add B2C Connection in the Command Palette. Four inputs follow: a name, the sandbox hostname, the account from your credentials and a code version. Press Enter after each one
Choose the active target
The first connection becomes active on its own. To switch later, hover another connection in Explorer and select its Activate Connection icon, or click the active connection's name in the status bar and pick one. To change the code version, click it in the status bar, or expand the connection, then Settings, and select the Change Code Version icon on the Code Version row. Check the site scope and Auto Upload state in the status bar, and keep automatic uploads off during setup
Verify without uploading
In Explorer, expand the connection, then Instance › Code Version › your code version. Confirm that it lists the cartridges on the sandbox, that the active connection and code version in the status bar are correct, and that your local cartridges show in the Cartridges view of VS Code's own Explorer (⇧⌘E on macOS, Ctrl+Shift+E on Windows and Linux)
Try one local edit
Open a script in a cartridge and try completion for dw. or a cartridge require path. Open an .isml template and try tag completion. These checks help confirm that the IDE recognizes your source files
When you are ready to send code to the sandbox, follow Deployment. Verify the target before enabling auto-upload or using a manual upload action. Selecting a code version in the IDE does not mean it has been activated for the storefront on the server
Adjust settings when needed
Open VS Code Settings and search for Intellij SFCC. Settings use the intellij-sfcc.* prefix; the Plugin Settings reference lists every key and its default. Automatic upload belongs to the active connection and is controlled from its status-bar action
Use the feature guides for ISML formatting and script intelligence. You do not need to paste a settings bundle to complete installation
Troubleshooting the first connection
| What you see | Next check |
|---|---|
| The account picker is empty | Open Credentials and add or sync the account, then reopen the connection form |
| Remote folders cannot be listed | Check the hostname, sandbox authentication method, WebDAV permissions, and any required VPN |
| The connection works but API actions fail | Configure the API client and permissions for that feature separately |
| Local cartridges are missing | Confirm you opened the correct project folder and included the cartridge sources |
| Overrides or routes resolve to the wrong project | Check the active connection, site scope, and cartridge path |